DELETE OBJECT statement

Deletes an object such as a widget, a procedure, a server, a socket, or an instance of a class. Deleting the object causes all allocated resources associated with the object to be returned to the system (except when otherwise noted).

Syntax

DELETE OBJECT { handle|object-reference}[ NO-ERROR ]

handle

A handle to an ABL handle-based object. The handle argument must be a variable of type HANDLE and must contain a valid handle.

If the handle parameter refers to a widget, the DELETE OBJECT statement is a synonym for the DELETE WIDGET statement.

If the handle parameter refers to a persistent procedure handle or proxy procedure handle, the DELETE OBJECT statement is a synonym for the DELETE PROCEDURE statement. This statement deletes a local persistent procedure handle immediately. For a proxy procedure handle, this statement deletes the handle immediately unless there is an outstanding asynchronous request on this handle (handle:ASYNC-REQUEST-COUNT is greater than zero (0)). If handle:ASYNC-REQUEST-COUNT is greater than zero (0), this statement raises the ERROR condition. Otherwise, the statement also sends a request to the AppServer to delete the corresponding remote persistent procedure on the AppServer. If the AppServer is executing any asynchronous requests ahead of it, the AVM queues the delete request (as with any asynchronous remote request) until the AppServer is available to handle it.

Note: This same behavior occurs if the remote procedure deletes itself (using DELETE...THIS-PROCEDURE) on the AppServer.

For more information on remote persistent procedures, see OpenEdge Application Server: Developing AppServer Applications.

If the handle parameter refers to a server handle, the DELETE OBJECT statement:

• Checks that the handle parameter refers to a valid server handle, and that the handle parameter's CONNECTED attribute is FALSE (no AppServer is connected to it). If one of these checks fails, the statement raises the ERROR condition.
• Deletes the handle immediately, if the server handle is valid, unless there is an outstanding asynchronous request on this handle (handle:ASYNC-REQUEST-COUNT is greater than zero (0)). If there is an outstanding asynchronous request, this statement raises the ERROR condition.

Deleting a server handle removes the handle from the server handle chain of the SESSION system handle, and resets SESSION:FIRST-SERVER and SESSION:LAST-SERVER if necessary. This also deletes all of the asynchronous request handles associated with the server and then deletes the server object.

If handle refers to an asynchronous request handle, the DELETE OBJECT statement takes one of the following actions:

• If the handle:COMPLETE attribute is FALSE, it raises the ERROR condition.
• If the handle:COMPLETE attribute is TRUE, it removes handle from the chain of asynchronous request handles referenced by the FIRST-ASYNC-REQUEST and the LAST-ASYNC-REQUEST attributes of the server handle, and deletes handle.

If this is a socket handle, the application must disconnect the socket from a port using the DISCONNECT( ) method before a socket object can be deleted. The DELETE OBJECT statement raises ERROR if an application deletes a socket object that is still associated with a port.

If this is a server socket handle, the application must call DISABLE-CONNECTIONS( ) before a server socket object can be deleted. The DELETE OBJECT statement raises ERROR if an application deletes a server socket object that is still listening for connections.

Where handle refers to a dynamic buffer, it is recommended practice to execute the DELETE OBJECT statement at the same level (that is, as part of the same sub-transaction) as the transaction that created the buffer.

object-reference

An object reference to a class instance. The object reference argument must be an ABL object reference variable, such as one defined using the DEFINE VARIABLE statement or the DEFINE PARAMETER statement with the CLASS option, and it must contain a valid object reference.

Note: You can validate an object reference by using the VALID-OBJECT function.

When you delete a class instance, the AVM invokes the destructor for the class and the destructor for each class in its inherited class hierarchy, if any. The destructor can be used for freeing resources allocated to the object when the object is deleted. At this time, the object context goes out of scope. In addition, the object is removed from the list of valid ABL class instances (session object chain) referenced by the FIRST-OBJECT attribute or LAST-OBJECT attribute of the SESSION system handle.

If you do not delete a class instance and you have not turned off automatic garbage collection using the No Garbage Collection (-nogc) startup parameter, the instance is deleted when there are no more references to it.

OpenEdge includes a performance tuning feature for ABL class-based applications that controls how the AVM deletes objects. The Re-usable Objects Cache (-reusableObjects) startup parameter specifies the number of deleted class objects that the AVM stores for later re-initialization. By default, -reusableObjects is set to 25. When you use -reusableObjects, the AVM transfers the deleted object for most ABL classes to a re-usable objects cache. If your application causes the AVM to instantiate the same class later, the stored object is re-initialized and removed from the cache. The re-initialized object has a new UUID and the same initial data as a new instance of the class. The re-use of the object saves much of the overhead of instantiating a class.

For most ABL classes, the AVM transfers the deleted object to a re-usable objects cache. The re-usable object cache provides a means for you to tune the performance of ABL class-based applications. If your application causes the AVM to instantiate the same class later, the stored object is re-initialized and removed from the cache. The re-initialized object has a new UUID and the same initial data as a new instance of the class. The re-use of the object saves much of the overhead of instantiating a class.

Note: The cache does not store .NET classes, .NET-derived ABL classes, classes with static elements, or classes compiled during your session.

NO-ERROR

Suppresses ABL errors or error messages that would otherwise occur and diverts them to the ERROR-STATUS system handle. If an error occurs, the action of the statement is not done and execution continues with the next statement. If the statement fails, any persistent side-effects of the statement are backed out. If the statement includes an expression that contains other executable elements, like methods, the work performed by these elements may or may not be done, depending on the order the AVM resolves the expression elements and the occurrence of the error.

To check for errors after a statement that uses the NO-ERROR option, you can:

• Check the ERROR-STATUS:ERROR attribute to see if the AVM raised the ERROR condition.
• Check if the ERROR-STATUS:NUM-MESSAGES attribute is greater than zero to see if the AVM generated error messages. ABL handle methods used in a block without a CATCH end block treat errors as warnings and do not raise ERROR, do not set the ERROR-STATUS:ERROR attribute, but do add messages to the ERROR-STATUS system handle. Therefore, this test is the better test for code using handle methods without CATCH end blocks. ABL handle methods used in a block with a CATCH end block raise ERROR and add messages to the error object generated by the AVM. In this case, the AVM does not update the ERROR-STATUS system handle.
• Use ERROR-STATUS:GET-MESSAGE( message-num ) to retrieve a particular message, where message-num is 1 for the first message.

If the statement does not include the NO-ERROR option, you can use a CATCH end block to handle errors raised by the statement.

Some other important usage notes on the NO-ERROR option are:

• NO-ERROR does not suppress errors that raise the STOP or QUIT condition.
• A CATCH statement, which introduces a CATCH end block, is analogous to a NO-ERROR option in that it also suppresses errors, but it does so for an entire block of code. It is different in that the error messages are contained in a class-based error object (generated by the AVM or explicitly thrown), as opposed to the ERROR-STATUS system handle. Also, if errors raised in the block are not handled by a compatible CATCH block, an ON ERROR phrase, or an UNDO statement, then the error is not suppressed, but handled with the default error processing for that block type.
• When a statement contains the NO-ERROR option and resides in a block with a CATCH end block, the NO-ERROR option takes precedence over the CATCH block. That is, an error raised on the statement with the NO-ERROR option will not be handled by a compatible CATCH end block. The error is redirected to the ERROR-STATUS system handle as normal.
• If an error object is thrown to a statement that includes the NO-ERROR option, then the information and messages in the error object are used to set the ERROR-STATUS system handle. This interoperability feature is important for those integrating code that uses the traditional NO-ERROR technique with the newer, structured error handling that features error objects and CATCH end blocks.

Notes

• When a temp-table object is passed as a TABLE-HANDLE output parameter, the deletion of the object following the DELETE OBJECT statement is postponed until the procedure goes out of scope. When the procedure returns, the TABLE-HANDLE is created, receives a copy of the original temp-table, and is then returned.
• The OUTPUT TABLE-HANDLE parameter creates a TEMP-TABLE in the target procedure, which is added to the SESSION widget-pool. You must use the DELETE OBJECT statement to delete this TEMP-TABLE when it is no longer needed, or you will create a memory leak.
• Using automatic garbage collection (the default), the AVM deletes each class instance when no references to the object exist other than on the session object chain (accessible using the FIRST-OBJECT attribute or LAST-OBJECT attribute of the SESSION system handle). When a class instance is garbage collected, its destructor runs as if you deleted the object using DELETE OBJECT. As with DELETE OBJECT, automatic garbage collection stores the deleted object in a re-usable object cache.
• You can turn off automatic garbage collection using the No Garbage Collection (-nogc) startup parameter. However, if you do so, you must decide when to use this statement to delete each class instance you no longer need. Furthermore, a class instance that has no other references still remains in memory. You must locate it by walking the session object chain and then delete it.
• The Re-usable Object Cache (-reusableObjects) startup parameter controls how many deleted class-based objects are cached. By default, the parameter is set to 25. You can disable this feature by setting the parameter value to zero. When the cache is full and you delete another object, the AVM uses a least-recently used scheme to make room in the cache.
• The AVM only uses an object in the re-usable object cache to re-instantiate the same class. It cannot use an object to instantiate another class in the same inheritance hierarchy. For example, Class B inherits Class A and is inherited by Class C. If the cache contains an instance of Class B, the AVM cannot use that object to help instantiate either an instance of Class A or Class C. The AVM can only use that object for a new instance of Class B.
• If you invoke DELETE OBJECT from within a class constructor, specifying the THIS-OBJECT system reference for object-reference, class instantiation stops, and the AVM invokes the destructor for the instantiating class and for each class in its class hierarchy where the constructor has already completed execution. After all destructors have completed, control returns to the statement following the statement that instantiated the class using the NEW function (classes), the NEW statement, or the DYNAMIC-NEW statement. When control returns from the context of a NEW statement or a DYNAMIC-NEW statement, the data element set to receive the object reference to the failed class instantiation receives the Unknown value (?).
• When you invoke DELETE OBJECT from within a class constructor, the object is stored to the re-usable object cache. By the time the instantiation reaches a constructor, the object data stored in the cache is already in memory. Even though the current instantiation never completes, the AVM can use the object data to instantiate another instance of the class at a later time without problems.
• If you need to terminate class instantiation within a constructor, Progress Software Corporation recommends that you use a RETURN ERROR or a THROW (as in the RETURN statement or UNDO statement, respectively). This has the same effect as using the DELETE OBJECT THIS-OBJECT statement and also raises ERROR on the statement that attempts to instantiate the class. This allows your application to handle the uninstantiated class condition using ABL error handling options, such as the CATCH statement or the NO-ERROR option on many statements.
• For more information on working with asynchronous remote procedures and event procedures, see OpenEdge Application Server: Developing AppServer Applications.
• For more information on working with socket and server socket objects, see OpenEdge Development: Programming Interfaces.
• For more information on working with class instances, see OpenEdge Development: Object-oriented Programming.
• Automatic garbage collection works for .NET objects, or for ABL objects that derive from .NET objects, similar to how it works for pure ABL class instances. However, .NET objects and the .NET components of an ABL-derived .NET object are also managed separately by .NET garbage collection. Thus, the release of memory held by a .NET object or an ABL-derived .NET object depends on both ABL and .NET garbage collection.
• For a .NET form object, you can typically invoke its Close( ) method or the System.Windows.Forms.Application:Exit( ) method (for non-modal forms) to both close the form and delete the associated object, making it available for .NET garbage collection. One instance where a form is not deleted using the Close( ) method is when a non-modal form is an invisible child form of a multiple-document interface (MDI). In this case, you must also invoke the DELETE OBJECT statement on the associated object reference, or otherwise remove all references to the form, to make the form available for .NET garbage collection.
• In a .NET event handler for the FormClosing event, if you do delete object references, do not delete the object reference to the form (sender) that published the FormClosing event. Otherwise, this causes the FormClosing event to be published a second time for the same form. If you need to delete the sender of an event associated with the closing of a .NET form, execute the DELETE OBJECT statement on the sender in an event handler for the FormClosed event of the form. However, note that with garbage collection, you typically do not need to delete any object references in a .NET event handler.
• In ABL, the .NET Dispose( ) method is also available for freeing resources held by a .NET object. Its main purpose is to clean up unmanaged resources, such as file handles or socket connections. A well-behaved object cleans these up in its destructor, but calling Dispose( ) forces this cleanup in a more timely manner. It is good practice to call Dispose( ) on any object that implements the IDisposable interface.
  Note: .NET automatically calls Dispose( ) on a non-modal form when it is closed, unless the form is shown as a dialog box. .NET simply hides the dialog when it is closed. However, the AVM calls Dispose( ) by default for dialogs that inherit from Progress.Windows.Form. The AVM does not do this if the DisposeDialogOnClose property of the form is set to FALSE. This can be set on a particular instance or globally using the No Dialog Dispose (-nodialogdispose) startup parameter. One use case for not calling Dispose( ) is if you want to re-use the form at a later time.

See also

DELETE PROCEDURE statement, DELETE WIDGET statement, DESTRUCTOR statement, ERROR-STATUS system handle, THIS-OBJECT system reference, RETURN statement, UNDO statement