Daylight v4.9
Release Date: 1 February 2008

Name

dt_dealloc - remove an object from the system

Generic Prototype

dt_dealloc(dt_Handle) => dt_Boolean

C Prototype

#include "dt_smiles.h"

dt_Boolean dt_dealloc(dt_Handle object)

FORTRAN Prototype

include 'dt_f_smiles.inc'

logical dt_f_dealloc(object)

integer*4 object

Description

Removes the given object from the system and revokes its handle. Frees all resources used by the object (memory, opened files, etc). Once revoked, a handle must not be used; doing so has undefined results, which may include crashes of the toolkit.

The function does not apply to all objects. For example, the cycles of a molecule are a derived property of a molecule and are only deallocated by functions which modify the molecules atoms or bonds (or when the molecule itself is deallocated).

Deallocating 'object' automatically deallocates any objects for which 'object' is the parent object. See dt_parent(3) for more details.

When a molecule is deallocated, all of its atoms, bonds and cycles are deallocated (all objects for which the molecule is its parent). All streams, depictions and conformations are also deallocated (all objects for which the molecule is its base).

When an atom is deallocated, all bonds which attached to that atom are deallocated. When a bond or atom is deallocated, its parent molecule must be in the modify-on state (see dt_mod_on(3)); the deallocation will fail otherwise. Deallocation of an atom or bond is considered a structural modification and causes all objects that have the molecule as their base object to be deallocated.

If a molecule is a component of a reaction (its parent is a reaction object), deallocating the molecule causes the molecule to be removed from the reaction. Streams over the reaction are revoked.

If 'object' is a reaction, deallocates all its component molecules and their atoms and bonds. Any objects with a base of the reaction or one of its molecules are deallocated (streams, path, depictions, etc. over the reaction).

If 'object' is a THOR server, closes all databases on the server, deallocates all TDT objects and their parts from those databases, and deallocates all datatype objects for the databases.

If 'object' is a Merlin server, closes all databases (pools) on the server, and deallocates all columns, hitlists, and datatypes from those databases.

If 'object' is a database on THOR, if there are no other clients, the database is closed. On Merlin, if the database is not marked hold (see dt_hold(3)) and there are no other clients, the pool is removed from the servers memory. Note that modified TDTs are not automatically written to the database when the database is closed. They must be explicitly written before closing or the modifications will be lost.

A datatype object cannot be deallocated.

If 'object' is a program, sends a message to the program, telling it to quit. Then, deallocates the object and revokes its handle. Note that if a program object is deallocated without first sending it (via dt_converse(3)) a NULL_OB message, its closing message will be discarded.

Return Value

Returns TRUE if the object was successfully removed, or FALSE if an error is detected or the object cannot be removed.

If 'object' is the NULL_OB, the function returns FALSE. The NULL_OB handle is never revoked.