Synopsis

PDX_MSGT mda_CreateEntity(long option, void *ent, MDA_PTR *db_ptr)

Purpose

Commit a memory entity to the model.

Description

An entity created with mda_MallocEntity, mda_MallocEntity2, or mda_DuplicateEntity will be committed to the model it was allocated in. If the entity was created with mda_MallocEntity then this will be the model which was current when mda_MallocEntity was called. If the entity was created with mda_MallocEntity2 the model which was specified to mda_MallocEntity2 will be used. Upon return from this function the entity will not be locked so mda_LockEntity must be called before the entity is accessed. The function mda_FreeEntity should not be called on the entity which was passed to this routine. If the MDA_RESERVED option is specified, the value in *db_ptr is assumed to be a database pointer previously reserved with either a call to mda_ReserveEntity or mda_DeleteEntity with the MDA_RESERVED option. If the MDA_LEAVE_LOCKED option is specified, the entity will be left locked and in the same state as following a call to mda_AllocateEntity (i.e. the entity will be marked as modified and will not have been written to disk yet).

If the MDA_SET_BACKPTRS option is set, the resulting entity will be traversed and any entities it references will have a backpointer set to the new entity. If this option is used, the caller must ensure that ent is in a traversable state (i.e. all count and array pointers set to appropriate values).

If ent was created with mda_MallocEntity or mda_MallocEntity2, the original database pointer for ent will be set to db_ptr (i.e. it will be an original entity). If ent was created with mda_DuplicateEntity or mda_DuplicateEntity2, the original database pointer for the entity which was duplicated will be used. See the mda_intro man page for more information on predecessor entities.

Input

option

MDA_RESERVED

The database pointer to be assigned to the new entity has been previously reserved and is specified in the db_ptr parameter. The default is to assign a new database pointer to the entity.

MDA_LEAVE_LOCKED

The entity will be left locked as if it had been created using mda_AllocateEntity. If this option is specified, it is up to the caller to call mda_UnlockEntity. The default is to leave the entity unlocked which means that the memory referenced by ent should not be accessed after this function returns.

MDA_SET_BACKPTRS

Entities referenced by ent will have a backpointer set to @a *db_ptr. The default is to not set backpointers.

ent

The entity to be committed to the model

db_ptr

Previously reserved database pointer (only required when MDA_RESERVED is specified)

Output

db_ptr

The database pointer of the newly created entity (unless MDA_RESERVED is specified in which case the value is left unchanged).

Return

MDA error code