Synopsis

(macro) PDX_MSGT mda_CopyEntity(long option, MDA_COPY_CHECK *func, void *src_ent, void *dst_ent)

Purpose

Recursively copy an entity.

Description

The entity structure specified by src_ent (and optionally the entities which it references) will be duplicated with the resulting entity structure being placed in *dst_ent. src_ent can be either a locked entity or an entity created via mda_MallocEntity. The resulting entity can be written to the database by calling mda_CreateEntity or freed by calling mda_FreeEntity. Backpointers will be correctly maintained for all entities in the tree except the pointers in dst_ent (because dst_ent does not have a database pointer). The calling routine can supply a function in func which determines if an entity referenced by src_ent should be copied. This allows an application to control what part of the entity tree is actually copied. If NULL is passed for func, the entire entity tree starting at src_ent will be duplicated. If a function is supplied, it must have the following binding: .RS 3 int copy_check (MDA_PTR db_ptr, MDA_PTR *new_ptr) .RE

The application function will be called for all PTR fields defined in the entity (including fields which are set to MDA_NULL_PTR). If the application function returns a value of 0, mda_CopyEntity will not copy the entity referenced by db_ptr nor anything it references. The field in the parent entity which pointed to db_ptr will be set to *new_ptr. To not copy a sub-tree and set the pointer to MDA_NULL_PTR, the application function would return a 0 with *new_ptr set to MDA_NULL_PTR. Alternatively, the application could return *new_ptr set to another entity.

If the application function returns a 1, mda_CopyEntity will recursively copy the entity referenced by db_ptr and the value in *new_ptr will be ignored.

The application function can use any of the mda functions except mda_CopyEntity and mda_CopyEntity2.

Multiple references to a particular entity will result in the entity being copied just once. The application function will still be called for each reference to the entity.

Because the dst_ent entity is not created in the database, a copy of src_ent will be created in the target model if a nested entity contains a pointer to src_ent.

This function uses mda_TraverseEntity to traverse src_ent. Consequently, the caller must ensure that src_ent is in a traversable state (i.e. all count and array pointers set to appropriate values).

Note that dst_ent is the address of the pointer to the resulting entity structure.

Input

option

Options (not used)

func

Function to determine if nested entity should be copied or NULL

src_ent

Entity to be copied

dst_ent

Address to store the copied entity structure pointer at

Output

dst_ent

Copy of src_ent

Return

MDA error code