Managing Dynamically-Allocated Storage

ILE allows you to directly manage run-time storage from your program by managing heaps. A heap is an area of storage used for allocations of dynamic storage. The amount of dynamic storage required by an application depends on the data being processed by the programs and procedures that use the heap.

To manage heaps, you can use:

The ALLOC, REALLOC, and DEALLOC operation codes
The %ALLOC and %REALLOC built-in functions
The ILE bindable APIs

You are not required to explicitly manage run-time storage. However, you may want to do so if you want to make use of dynamically allocated run-time storage. For example, you may want to do this if you do not know exactly how large an array or multiple-occurrence data structure should be. You could define the array or data structure as BASED, and acquire the actual storage for the array or data structure once your program determines how large it should be.

Figure 53. Allocating, sorting and searching dynamically-allocated arrays

 * Two counters are kept:
 * 1. The current number of array elements
 * 2. The number of array elements that are allocated for the array

D arrInfo         DS                  QUALIFIED
D   pArr                          *   INZ(*NULL)
D   numElems                    10I 0 INZ(0)
D   numAlloc                    10I 0 INZ(0)
D arr             S             20A   VARYING DIM(32767)
D                                     BASED(arrInfo.pArr)
D i               S             10I 0
 /free
    // Allocate storage for a few array elements
    // (The number of elements that the array is considered to
    // actually have remains zero.)

    arrInfo.numAlloc = 2;
    arrInfo.pArr = %alloc(arrInfo.numAlloc * %size(arr));

    // Add two elements to the array

    if arrInfo.numAlloc < arrInfo.numElems + 2;
      // There is no room for the new elements.
      // Allocate a few more elements.

      arrInfo.numAlloc += 10;
      arrInfo.pArr = %realloc (arrInfo.pArr
                             : arrInfo.numAlloc * %size(arr));
    endif;
    arrInfo.numElems += 1;
    arr(arrInfo.numElems) = 'XYZ Electronics';
    arrInfo.numElems += 1;
    arr(arrInfo.numElems) = 'ABC Tools';

    // Search the array

    i = %lookup ('XYZ Electronics' : arr : 1 : arrInfo.numElems);
    // i = 1

    // Sort the array

    sorta %subarr(arr : 1 : arrInfo.numElems);

    // Search the array again

    i = %lookup ('XYZ Electronics' : arr : 1 : arrInfo.numElems);
    // Now, i = 2, since the array is now sorted

    // Remove the last element from the array

    arrInfo.numElems -= 1;

    // Clear the array
    // This can be done simply by setting the current number of
    // elements to zero.  It is not necessary to actually clear
    // the data in the previously used elements.

    arrInfo.numElems = 0;

    // Free the storage for the array

    dealloc arrInfo.pArr;
    reset arrInfo;

    return;

There are two types of heaps available on the system: a default heap and a user-created heap. The RPG storage management operations use the default heap. The following sections show how to use RPG storage management operations with the default heap, and also how to create and use your own heap using the storage management APIs. For more information on user-created heaps and other ILE storage management concepts refer to ILE Concepts.

[ Top of Page | Previous Page | Next Page | Contents | Index ]