Synopsis

PDX_MSGT map_DefineMapping(long option, MAP_TABLE *table, char *name, DDF *ddf, DDF_TF tf, DDF *target_ddf, DDF_TF target_tf, MAP_FUNCTION *function)

Purpose

Define a new simple mapping.

Description

A simple mapping definition named name will be added to table. The mapping is referenced in subsequent map calls using the character string name which must be unique across all mappings defined in table. The entity type which is to have the mapping applied is specified in the tf parameter. Wildcarding can be performed so that the same mapping function is assigned to multiple forms. A wildcard is specified using the DDF_ANY_FORM define for the form passed in tf. For example, to define a mapping for all forms of the entity type 10, the caller would pass the following for the tf argument:

.RS 3 ddf_MakeTF (10, DDF_ANY_FORM) .RE

Since type/forms are not unique across models, the ddf in which the type/form is defined is specified with the ddf argument. The DDF for a model can be obtained using mda_GetModelDDF. The target_ddf argument specifies the DDF which target_tf is defined in. If the mapping always generates the exact same type and form of entity, the resulting TF should be specified in target_tf. This makes the mapping chainable so that its output can be passed to another mapping as part of a mapping list. Note the requirement is that the result be single a type/form, not just type. If the mapping may result in different type/forms of entities, the value DDF_ANY_TF must be specified for target_tf.

If the mapping generates entities which are not in a PDElib model (i.e. an end mapping), NULL should be specified for target_ddf and DDF_NULL_TF should be specified for target_tf. The function which applies this mapping is specified in the function parameter. This function must have the following binding:

.RS 3 PDX_MSGT function (MDA_PTR db_ptr, MAP_INFO *info) .RE

If function calls map_ProcessEntity with the resulting entities, the MAP_GENERAL option must be specified. If this option is not specified, the mapping is assumed to be an end mapping which does not pass its results to map_ProcessEntity for further processing. function must meet certain requirements if the MAP_GENERAL option is specified. See map_intro for additional information.

The MAP_TRANSIENT option may be specified in conjunction with MAP_GENERAL to indicate that the entities passed to map_ProcessEntity are transient (temporary) entities which are created by function. This allows map_ProcessEntity to determine if an entity must be duplicated before it can be committed. If function passes existing entities (as in a "decomposition" type mapping), or a mixture of existing and temporary entities, this option should not be specified.

After a mapping has been defined with map_DefineMapping, it must be enabled with map_EnableMapping if it is to be applied in map_DispatchEntity. Alternatively, the MAP_ENABLE option can be used which combines the functionality of a call to map_DefineMapping followed by a call to map_EnableMapping. Note that using the MAP_ENABLE option does not allow the caller to specify optional parameters for the mapping as it can with map_EnableMapping.

Multiple mappings can be created for an entity type by calling this function multiple times with the same ddf and tf arguments.

Input

option

MAP_ENABLE

Enables the mapping in addition to defining it. By default, the mapping must be enabled by a subsequent call to map_EnableMapping.

MAP_GENERAL

Indicates that function will pass the resulting entities to map_ProcessEntity for further processing.

MAP_TRANSIENT

Indicates that the entities passed by function to map_ProcessEntity are created by function. This option can only be used in conjunction with MAP_GENERAL.

table

Mapping table to define the mapping in

name

Name to be assigned to the mapping

ddf

DDF in which tf is defined

tf

The type/form of the entity the mapping is to be applied

target_ddf

The DDF in which the resulting entity type/forms are defined in.

target_tf

The unique type/form which this mapping generates or DDF_ANY_TF if it may produce different type/forms

function

Function which performs the mapping

Return

MAP error code