Synopsis

(macro) PDX_MSGT mda_DeleteEntity(long option, MDA_PTR db_ptr)

Purpose

Delete an entity from the database.

Description

The specified entity will be deleted. No clean up will be performed on entities which reference the deleted entity or entities which it references. The freed database pointer may be reused by mda_AllocateEntity so the application should perform any required cleanup before deleting the entity. If the MDA_FORCE_DELETE option is used to delete an entity which is referenced from another, the application must not call mda_ModifyPtr or mda_DeletePtr with the child pointer equal to db_ptr after it has been deleted.

By default, when backpointers are enabled, this function will call mda_DeleteBackPtrs to remove the backpointer references from the children of db_ptr. The manual page for mda_DeleteBackPtrs lists the implications of doing this. To avoid invoking mda_DeleteBackPtrs, the MDA_NO_DELETE_BACK_PTRS option may be specified. If this option is used, it is up to the application to ensure that all references from db_ptr to other entities have been removed using mda_ModifyPtr or mda_DeletePtr before calling this function. This option also causes backpointer references from db_ptr to its parents to be preserved. The MDA_NO_DELETE_PARENT_PTRS will preserve backpointer references from db_ptr to its parents. Normally this option is used in conjunction with MDA_RESERVED to delete an entity and leave all of the backpointer information in place so that a subsequent call can be made to mda_ReplaceDbptr.

If the MDA_RESERVED option is specified, the entity will be deleted as described above but db_ptr will be left in a reserved state (the same as if it had been returned from the function mda_ReserveEntity). This allows an entity to be deleted and then a replacement with the same database pointer can be created.

An MDA_ENT_DELETED event will be generated if the entity can be deleted (i.e. if it is referenced from other entities and the MDA_FORCE_DELETE option is not specified, the event will not be generated). The callback function will be invoked before the entity or parent references are deleted so that the callback function can access them before the deletion.

Input

option

MDA_NO_FREE

Do not free memory associated with the entity, just remove the instance from the database. This results in an entity identical to one created via mda_MallocEntity. Call the function mda_FreeEntity to free memory associated with the entity. Note that the entity MUST be locked.

MDA_FORCE_DELETE

Delete the entity regardless of whether or not it is referenced from another entity. If this option is used it is up to the caller to fix the references to this entity. If this option is not specified and the entity is referenced from another entity, the error MDA_HAS_PARENTS will be returned and the entity will not be deleted. If backpointers are not enabled for the model which the entity is defined in then this option does not have any effect.

MDA_RESERVED

Leave db_ptr marked as being reserved.

MDA_NO_DELETE_BACK_PTRS

Do not invoke the mda_DeleteBackPtrs function and do not remove backpointer references from db_ptr to its parents.

MDA_NO_DELETE_PARENT_PTRS

Do not remove backpointer references from db_ptr to its parents.

db_ptr

Entity to be deleted

Return

MDA error code