This , of course, can lead to a host of ugly sorts of bugs not the least of which is not having any idea where the error happened or why.

Here is a simple example that demonstrates a Phantom Error:

DEFINE NEW GLOBAL SHARED VARIABLE myHandle AS HANDLE NO-UNDO.
main: DO ON ERROR UNDO main, RETRY main:
  IF RETRY THEN do:
    MESSAGE RETURN-VALUE error-status:get-message(1) VIEW-AS ALERT-BOX.
    LEAVE main.
  END.
  RUN someProc IN myHandle.
END.

You’ll notice that both return-value and get-message(1) return blank.

If you happen to be in a terminal based procedure editor, however, you will receive the error message in the “message area” at the bottom. Unfortunately, this doesn’t do much good for server code.

As a consequence, server code will typically swallow these Phantom Errors at worst, or report the error out of context at best.

So, what can be done? Diligent error trapping is called for. Protect the code by always testing handles before using them.

Unfortunately, this isn’t the only type of code that will produce a Phantom Error. We will discuss other Phantom Errors under the Tag “Phantom Errors” in other posts.

When a variable is defined, the Progress runtime client (Virtual Machine) allocates memory at runtime for that variable. Once the variable is out of scope, the memory is released and everyone is happy. Progress programmers have grown comfortable with this design and obliviously define variables whenever they are needed knowing that they will be de-allocated automagically by the Progress VM.

Then came dynamic objects.

Progress programmers were overjoyed! They could now create temp-tables, buttons, queries all on the fly at runtime. No more convoluted if-then statements or .i’s or having to code a different “for each” for every combination of where clause.

However, as with any power bestowing feature, there is a dark side to this wonderful new world of dynamic 4gl: memory management. Most programmers never really stopped to consider the fact that if something is created dynamically at runtime, the VM has no way of knowing the scope. It cannot tell when to release the memory required for the dynamic object. REMEMBER: the scope of the variable you happen to assign the object to HAS NO BEARING on the scope of the OBJECT since it can be passed around. In other words, the scope of the variable holding the HANDLE to the object is NOT bound to the OBJECT itself. The scope of ALL OBJECTS are always at the SESSION. This applies to GUI widgets, dynamic queries, temp-tables, etc.

Java (and other VM’s) solve this through the use of a separate execution thread running concurrently called a Garbage Collector. Its job is to scan memory and find dynamic objects that are no longer “reachable” and release their memory. Unfortunately, the Progress VM has no such thread/concept.

To add insult to injury, not only does this leak memory but it also causes progressively worse performance: The more widgets in memory, the more time it takes to create another widget. Here are three examples (run on a 2.1ghz processor):

Button Handles

Minimum memory required/lost per Button Handle: 512 bytes

Query Handles

Minimum memory required/lost per Query Handle: 1024 bytes

Temp-Table Handles

Min. memory required/lost per Temp-Table Handle: 512 bytes

So, as you can see, from both a memory and CPU footprint standpoints, it is very important to be sure to clean up your objects.

This may seem like a large number of handles, but remember two important points:
1. This is at the session level. This means that if a.p calls b.p which creates objects then those will exist for the life of the session: THERE IS NO SCOPE other than SESSION FOR DYNAMIC OBJECTS and they are NEVER automatically reclaimed!
2. If the programs are running as part of a long-running session such as AppServer, EagleIQ server or Webspeed, then you have to consider the cumulative affect over days, weeks or months.
Also note that if it is a temp-table, it could potentially have a much larger memory footprint.

So, what must be done?
It is up to the Progress programmer to clean up each and every dynamic object created using the “delete object” command.
It may be appropriate to create a widget-pool in which to assign your objects so you can just delete the pool and all the objects within will be released as well. In fact, if you create a non-persistent widget-pool, it will be automatically deleted when it goes out of scope. Creating the object into a non-persistent pool will make it behave as if it were scoped at the level that the widget-pool is created: in effect, making it behave as if it were statically defined.

If you don’t use a non-persistent widget-pool, then It is also important to be sure the “clean up” code is executed even when there is an error. For example, the following will bleed memory if an error condition is raised within the blah blah:

      procedure doQuery:
          def var qh as handle.
          create query qh.
          /* so some business logic here */
          do while true:
               blah blah
          end.
          delete object qh.
     end.

However, if you create a non-persistent widget pool, then it is automatically deleted when it goes out of scope. So the following will not leak memory even if an error condition happens:

procedure doQuery:
    def var qh as handle.
    create widget-pool "wp".
    create query qh in widget-pool "wp".
    /* so some business logic here */
    do while true:
         blah blah
    end.
    delete object qh.
end.

The widget-pool may be defined at the .p level as well. In this case the pool is deleted when the .p is exited.

Oh, by the way, persistent procedures and memptr’s are two other constructs that have a session level scope. However, they cannot be part of a widget-pool and therefore must be handled individually.