Release Date: 1 February 2008
Namedt_mod_off - specify that an object may not be modified
Generic Prototypedt_mod_off(dt_Handle) => dt_Boolean
C Prototype#include "dt_smiles.h"
dt_Boolean dt_mod_off(dt_Handle object)
FORTRAN Prototypeinclude 'dt_f_smiles.inc'
DescriptionPuts the given object in the modify-off state. Molecules and reactions in this state may not be modified. If the object is already in the modify-off state, this function has no effect and is silently ignored.
For a molecule, this function causes the molecules structure to be analyzed; its properties may change as a result. The most notable change is to the aromaticity of constituents. A recalculation of contained cycles may also be performed.
For a reaction, this function causes all of its component molecules to be structurally analyzed and modified.
If dt_mod_off() is applied to a molecule which is part of a reaction, this function is identical to calling dt_mod_off() for its parent reaction. In effect, a reaction and its component molecules are treated as a single unit for structural modification; setting mod-off for any part sets mod-off for the whole.
The following functions may be applied only to molecules in the modify-off state: dt_arbsmiles(3), dt_cansmiles(3), dt_cansmi_stream(3), dt_symclass(3), dt_symorder(3).
Return ValueReturns the success (TRUE) or failure (FALSE) of the operation. There will be an error if the properties of the molecule are not internally consistent. The most likely cause for this error is if a valid Kekule structure can not be built for the molecule.
If there is an error, the object is deallocated and the handles for it and its constituent parts are revoked, just as thought dt_dealloc(3) had been called for the object. This is a side-effect of the structure-analysis functions, if they fail, the object is left in an unusable state. Objects that are 'precious' should be copied prior to invoking dt_mod_off(3). If it returns TRUE, then the copy can be discarded.
Related Topicsdt_mod_is_on(3) dt_mod_on(3)