Synopsis

PDX_MSGT mda_UnlockEntity(long option, MDA_PTR db_ptr)

Purpose

Unlock an entity from memory.

Description

The specified memory will be unlocked so that it may be swapped out to disk when memory is needed to swap another entity in. Various options may be specified to control how the entity is unlocked. Memory pointers in the application to the entity may become invalid anytime after this function is called because the entity may be swapped out. Note that if the entity was allocated in the entity cache then calling this function does not remove the it from the cache. Therefore, if mda_LockEntity is called fairly soon after this function, the entity will probably be in memory still and will not require swapping. If the MDA_MODIFIED option is specified the entity will be rewritten to disk when it is swapped out. The MDA_MODIFIED option does not need to be specified if this is the first unlock call after creating the entity with mda_AllocateEntity or mda_AllocateEntity2 or if the entity was marked as modified with mda_MarkEntityModified. The MDA_INVALIDATE option indicates that the memory copy of the entity was changed by the application since it was swapped in and that the cache entry is no longer valid. This means that the next time the entity is locked it will be swapped in from disk. The MDA_INVALIDATE and MDA_MODIFIED options can not both be specified and MDA_INVALIDATE should never be specified in the first unlock call after creating the entity with mda_AllocateEntity or mda_AllocateEntity2. The MDA_FREE option removes the entity from the model by calling mda_DeleteEntity with the MDA_NOOPT option. See mda_DeleteEntity for restrictions on deleting entities. Note that the application must call mda_DeleteEntity if any options need to be specified. Normally this function must be called as many times as mda_LockEntity was called with db_ptr for the entity to be unlocked. These multiple locks can be ignored by using the MDA_FORCE_UNLOCK option.

If the MDA_MODIFIED option is specified, an MDA_ENT_MODIFIED event will be generated and the appropriate callback invoked. The argument passed to the callback function will be the address of the database pointer which was unlocked with modify. See mda_SetCallBack for further information.

Input

option

MDA_MODIFIED

The entity has been modified since it was locked and the changes should be saved if the entity gets swapped out. Mutually exclusive with MDA_INVALIDATE.

MDA_INVALIDATE

The entity has been modified since it was locked but the changes should not be saved and the copy of the entity in the cache should be marked as invalid. Mutually exclusive with MDA_MODIFIED.

MDA_FREE

The entity should be deleted from the database. If MDA_MODIFED or MDA_INVALIDATE are specified in addition to MDA_FREE, the former options will be ignored.

MDA_FORCE_UNLOCK

The entity should be unlocked regardless of how many times mda_LockEntity was called with the entity. If not specified, this function must be called the same number of times as mda_LockEntity was called for the entity to be unlocked.

MDA_CHECK_ENTITY

Call mda_DbgCheckEntity to verify the integrity of the entity in the model

db_ptr

The entity which is to be unlocked

Return

MDA error code