Synopsis
int OMdestroy_obj (
OMobj_id object,
int mode );
OMdestroy_objis a low level routine used for destroying objects. Normally, users use the routine OMuser_destroy_obj to destroy an object. This routine does not remove connections to this object and therefore only destroys the object when the last connection is deleted.
Description
OMdestroy_obj decrements an object's reference count. If the reference count is 0, it also deletes the object. Depending on the mode argument, it may also call OMdel_subobj to remove the object from the parent's subobject list.
The Object Manager maintains a reference count for each object, indicating the extent to which the object is in use. For example, you create an object, either in V or with a routine such as OMcreate_obj. The object's reference count is 1. If another object connects to the object, the object's reference count is incremented. If the connection to the object is removed, the object's reference count is decremented. An object's reference count can be incremented explicitly with a call to OMadd_to_refcnt. If the object's reference count is 0, which can happen only on a call to OMdestroy_obj, the object is deleted.
Arguments
object
The id of the object being deleted.
mode
A mode indicating whether the routine should call OMdel_subobj after decrementing the object's reference count. If called, OMdel_subobj removes the object from its parent so that the object now has a null parent id.
Specify one of the following:
• 0 -- Call OMdel_subobj only if the reference count is decremented to 0.
• OM_DESTROY_CHILD -- Do not call OMdel_subobj, regardless of the reference count. This flag should not be used by users of this routine. It is used by the parent object itself when it destroys its list of subobjects explicitly.
• OM_DESTROY_SUBOBJ -- Call OMdel_subobj, regardless of the reference count. You should use this flag if you want the object deleted from the object hierarchy regardless of whether or not it is actually deleted. This removes the object from the Network Editor if it is currently being displayed. You should use this flag if you are deleting this object on behalf of the user of the object. Otherwise, the user might be able to delete the object again using the Network Editor or VCP.
Returned value
0 if the reference count is greater than 0 after being decremented; 1 if the reference count is 0 after being decremented; -1 if an error has occurred, regardless of the reference count.
See also