Synopsis

PDX_MSGT map_DefineMappingList(long option, MAP_TABLE *table, char *name, ...)

Purpose

Define a mapping list.

Description

A mapping list named name will be added to table. Mapping lists provide a mechanism for referencing a list of mappings using a single name. An ordered list of mapping names is specified following the @name argument. The end of the list is indicated by a NULL pointer as in the following example:

.nf map_DefineMappingList ( MAP_NOOPT, table, "CAD arc -> CAD polyline", "CAD arc -> gdx_arc", "gdx_arc -> gdx_polyline", "gdx_polyline -> CAD polyline", NULL ); .fi

Whenever the "CAD arc -> CAD polyline" mapping is executed, the "CAD arc -> gdx_arc", "gdx_arc -> gdx_polyline", and "gdx_polyline -> CAD polyline" mappings will be invoked in sequence.

All but the last mapping to be included in the mapping list must be chainable (i.e. the target_tf parameter to map_DefineMapping is not DDF_ANY_TF). This indicates that the mapping will only pass a single type of entity back into the dispatcher. If all of the mappings to be included are chainable, the resulting mapping list can be included in the definition of another mapping list. If the last mapping in the list is not chainable, the resulting mapping list can not be nested in another mapping list.

The mapping list is associated with the DTF of the first mapping specified and does not affect the mapping of intermediate types in the mapping list. This means that in the above example, the "gdx_arc -> gdx_polyline" mapping will only be invoked if the gdx_arc was created from the "CAD arc -> gdx_arc" mapping.

The models used for storing intermediate entities (those resulting from all but the last mapping in the list) will be determined using the default rules as described in map_EnableMapping.

The mapping list is considered to be a single mapping in that the application dispatcher, if one is defined, is only called with the results of the final mapping. In the above example, the CAD polyline would be passed to the dispatcher but none of the intermediate entities would be.

After a mapping list has been defined with map_DefineMappingList, 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_DefineMappingList 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.

The mappings in the mapping list must be defined prior to calling map_DefineMappingList.

Multiple mapping lists can be created for an entity type by calling this function multiple times.

If the MAP_STRING_ARGS option is specified, then the variable arguments consist of a single character string with the mapping list embedded in it. Each mapping in the list must be enclosed in either single or double quotes and must be separated by commas. Whitespace between the mapping names and commas is ignored. The NULL at the end of the variable argument list is optional if the MAP_STRING_ARGS option is used.

The preceding example specified as a character string is shown below. Note that the string is shown split across 4 lines for clarity.

.nf map_DefineMappingList ( MAP_STRING_ARGS, table, "'CAD arc -> CAD polyline', \ 'CAD arc -> gdx_arc', \ 'gdx_arc -> gdx_polyline', \ 'gdx_polyline -> CAD polyline'" ); .fi

Input

option

MAP_ENABLE

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

MAP_STRING_ARGS

The mapping list corresponding to name is expressed as a string rather than individual arguments.

table

Mapping table to define the mapping list in

name

Name to be assigned to the mapping list @a ... List of character strings (or a single string with multiple embedded mapping names if the MAP_STRING_ARGS is specified) defining the mappings which this mapping will be equivalent to. The list is terminated with a NULL pointer (optional if MAP_STRING_ARGS is used).

Return

MAP error code