Synopsis

(macro) PDX_MSGT mda_AllocateEntity(long option, DDF_TF tf, void *ent, MDA_PTR *db_ptr)

Purpose

Allocate a new entity in the current model.

Description

An entity with the specified TF will be allocated in the current model. The ent argument specifies the address of the pointer to the entity. If the MDA_NO_LOCK option is not specified, the entity is locked as if the function mda_LockEntity and mda_MarkEntityModified had been called with db_ptr. This eliminates the need to specify the MDA_MODIFIED option when calling mda_UnlockEntity. If the MDA_NO_LOCK option is specified then the entity will not be locked in memory and the contents of @a *ent will not be changed (in this case NULL may be passed for ent). This allows an application to reserve an entity without locking it. If MDA_NO_CACHE is specified the entity will not be allocated in the entity cache (this means that the entity will have to be swapped from disk if it is unlocked and then locked again). MDA_NO_CACHE should be specified whenever an entity will be locked for an extended duration so that it does not use up space in the cache. If MDA_RESERVED is specified the value in *db_ptr is assumed to be a database pointer previously reserved with a call to mda_ReserveEntity, mda_ReserveEntity2, or mda_DeleteEntity with the MDA_RESERVED option. In this case, the entity will be allocated in the model which db_ptr was reserved in.

After this function is called the original database pointer for db_ptr will be set to db_ptr indicating that it is an original entity. See the mda_intro man page for more information on predecessor entities.

The function mda_AllocateEntity2 is identical to this function but allows you to specify the model in which to allocate the new entity.

Input

option

MDA_NO_CACHE

This option is obsolete, and no effect.

MDA_NO_LOCK

If specified the entity will not be locked upon return and the function mda_LockEntity must be called before the entity can be accessed. The default is to lock the entity and mark it as being modified.

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_DEFAULT_FIELDS

Initialize fields to default values.

tf

The TF of the entity to be allocated

ent

The location of the pointer to the entity

db_ptr

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

Output

ent

The location of the entity

db_ptr

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

Return

MDA error code