RELEASE OBJECT statement

Releases the specified COM object (Automation object or ActiveX control) and removes all internal structures associated with the handle to the object.

Syntax

RELEASE OBJECT COM-hdl-var[ NO-ERROR ]

COM-hdl-var

A COM-HANDLE variable that references a valid COM object.

NO-ERROR

The NO-ERROR option is used to prevent the statement from raising ERROR and displaying error messages.

Example

This procedure fragment shows a control named hc_CmdButton being loaded into a control-frame and the handle to the control (controlHdl) being obtained using the control name (hc_CmdButton) property. Later, it releases the control and deletes the parent control-frame widget (CFWidHdl).

DEFINE VARIABLE CFWidHdl   AS HANDLE     NO-UNDO.
DEFINE VARIABLE CFComHdl   AS COM-HANDLE NO-UNDO.
DEFINE VARIABLE controlHdl AS COM-HANDLE NO-UNDO.

/* Create frame foo ... */
CREATE CONTROL-FRAME CFWidHdl ASSIGN 
  FRAME = FRAME foo:HANDLE
  NAME  = "ctlFrame1".

CFComHdl = CFWidHdl:COM-HANDLE.
CFComHdl:LoadControls(hc_CmdButton.wrx, "hc_CmdButton").

controlHdl = CFComHdl:hc_CmdButton.
controlHdl:BgColor = RGB-VALUE(0,128,0).

/* Do some more stuff ... WAIT-FOR ... */
RELEASE OBJECT controlHdl. /* NOTE: Not really necessary */
DELETE WIDGET CFWidHdl.

For an example of the RELEASE OBJECT statement applied to Automation objects, see the CREATE automation object statement entry.

Notes

• After this statement completes, any other component handles that reference the object are invalid. If you attempt to reference the object using one of these handles, the AVM returns an invalid handle error. It is also possible for a newly instantiated COM object to get the same handle as one that has been released. The AVM does not detect that this occurs. In this case, the "old" handle is valid, but it references a different control. Thus, it is a good practice to set any COM-HANDLE variables that reference a released COM object to the Unknown value (?).
• The released COM object remains active as long as any other COM object has a valid reference to it. In the case of an ActiveX control, the parent control-frame is a COM object that references the control. All other component handle references you establish in the ABL session represent a second reference to the COM object. Thus, when you release one of these component handles, the released COM object remains active as long as the parent control-frame COM object is still active. To release the parent control-frame COM object and complete the release of the ActiveX control, you must follow any release of the ActiveX control by a delete of the parent control-frame widget.
• When you delete a control-frame widget, the AVM releases all associated ActiveX controls automatically, whether or not you release them individually.
• When the session ends, the AVM automatically releases any active COM objects you have not released individually.

See also

CREATE automation object statement, DELETE WIDGET statement, DELETE WIDGET-POOL statement, NO-ERROR option