Reclaiming memory used by Gen GUIObject usage in applications

Document ID : KB000027738
Last Modified Date : 14/02/2018
Show Technical Document Details


In the effort to conform to the ActiveX model we have had to tighten the sensitivity to correct GUIObject usage. Any attribute with domain type of GUIObject must be reset to null via the Action Diagram statement "SET <GUIObject> to NOTHING", regardless of how the object was acquired. A GUIObject attribute is a pointer to reference counted memory, which must be cleaned up when it is no longer needed.

Typically in application logic a GUIObject attribute is used to temporarily reference various objects as required to interact with those objects. It's possible for a GUIObject to contain a reference to an object even though that object no longer exists. When application logic sets a GUIObject attribute to a new reference, any existing object referenced by that GUIObject is first released before being set to the new value. When a GUIObject attribute contains an object reference and that object still exists and has not been destroyed, the GUIObject can successfully be set to a new value without first setting the GUIObject to NOTHING. But if that initial object no longer exists, then the release of that reference will follow an invalid pointer to a destroyed object. In prior versions of Gen, imperfect management of those objects within the GUI Runtime allowed certain instances of this to work successfully. Setting the GUIObject to NOTHING when its reference is no longer required before the object is destroyed (such as in a close window event) provides the correct release of the object and initialization of the GUIObject attribute. This is not an optional statement and will be required in all future releases. Failure to appropriately set a GUIObject to NOTHING before that object is destroyed can cause undesirable behavior, ranging from a very large memory leak to abnormal termination. Similarly, setting a GUIObject to NOTHING after the object has been destroyed can also result in problems. Ultimately, the impact is that existing applications may have worked correctly in earlier releases but could now fail.



In order to help customers detect whether an abnormal termination is a result of a model inconsistency or a GUI Runtime issue, a diagnostic tool has been provided. The tool provides the ability to run an application in a diagnostic mode to identify Action Diagram problems where a GUIObject attribute view is not correctly released using the SET <GUIObject> to NOTHING statement. This diagnostics tool can be invoked by an environment variable setting or merely by executing the application using the PAD Trace tool. When executing under diagnostics mode, all add references, releases, and deletes of Gen OLE aware objects will be logged. When a release of a GUIObject that has already been deleted has been requested (i.e. via a window close), an error dialog is presented. The Error dialog describes the event and line number of the action diagram statement requesting the release, along with the event and line number of the action diagram statement that initially retrieved the GUIObject IDispatch value. These and other details in the error message, along with PAD tracing of the application, help identify what object and statements are causing problems. An environment variable setting of:

IEFTRACEGUIOBJECTS=ERROR (or when executing under PAD Trace)provides the above error dialog.

IEFTRACEGUIOBJECTS=WARNING provides additional warning dialogs when abuse is detected, but not yet fatal.

IEFTRACEGUIOBJECTS=LOG provides a log recording each event. The output of this log requires executing the application within Microsoft's Visual Studio, with the log written to the Debug window of Visual Studio. Execute the application as "msdev loadmodulename.exe trancode" to start the application within Visual Studio.

IEFTRACEGUIOBJECTS=FIX quietly suppresses potentially fatal "releases", before they become application failures.

Warning: This logging is expensive processing, but suitable for debugging an application by the customer in his shop. Executing with IEFTRACEGUIOBJECTS=FIX is not intended as a production solution to inadequate action diagram logic. There is a significantly higher risk of out-of-memory failures and steady performance degradation if IEFTRACEGUIOBJECTS is set to any value in a production environment.

If an error dialog is displayed that refers to the GUIObject view containing the IDispatch address of one of the following collection objects: CListColumnItem, CListItem, CListPermitted, CListRowItem, or CMenu; the dialog message error should be ignored and the option "NO" button should be selected.