Synopsis

PDX_MSGT map_DefineConditionalMapping(long option, MAP_TABLE *table, char *name, DDF *ddf, DDF_TF tf, MAP_FUNCTION *function, ...)

Purpose

Define a conditional mapping.

Description

A conditional mapping named name will be added to table. Conditional mappings provide a mechanism for conditionally selecting mappings from within a conditional mapping function defined in @a function. An ordered list of component mapping names is specified following the @function argument. The end of the list is indicated by a NULL pointer as in the following example:

.nf map_DefineConditionalMapping ( MAP_NOOPT, table, "CAD arc -> CAD polyline or CAD line", &cad_ddf, cad_arc_tf, function, "CAD arc -> CAD polyline", "CAD arc -> CAD line", NULL ); .fi

The component mappings that are specified can be either simple mappings, mapping lists, or other conditional mappings. It is thus possible to nest conditionals and mapping lists. The component mappings must be invoked by calling map_InvokeMapping with the chosen component from the conditional function defined here. Whenever the "CAD arc -> CAD polyline or CAD line" mapping is executed, the associated function will determine which mapping path to take. In this example, the function can choose to map the CAD arc to either a CAD polyline or a CAD line. Once a path has been chosen, map_InvokeMapping is called with the name of the selected component mapping.

In order to nest conditional mappings, the entity type passed into the nested conditional must match the expected type of the nested conditional. The conditional mapping is associated with the DTF that is made by combining the ddf and tf that are passed in. Component mappings must have a source DTF that corresponds to this calculated DTF. The component mappings will only be invoked if map_InvokeMapping specifically invokes them. This means that in the above example, the "CAD arc -> CAD line" mapping will only be invoked if map_InvokeMapping is called with the "CAD arc -> CAD line" mapping. The models used for storing intermediate entities (those resulting from all but the last mappings of the outermost conditional mapping) will be determined using the default rules as described in map_EnableMapping.

Conditional mappings are 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 of the outermost conditional.

After a conditional mapping has been defined with map_DefineConditionalMapping, 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_DefineConditionalMapping 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 conditional mapping must be defined prior to calling map_DefineConditionalMapping.

Multiple conditional mapping can be created for an entity type by calling this function multiple times, but the output of the previous must match the input of the next.

If the MAP_STRING_ARGS option is specified, then the variable arguments consist of a single character string with the conditional mappings 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_DefineConditionalMapping ( MAP_STRING_ARGS, table, "CAD arc -> CAD polyline or CAD line", &cad_ddf, cad_arc_tf, function, "'CAD arc -> CAD polyline', \ 'gdx_arc -> CAD line'" ); .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 conditional mapping in

name

Name to be assigned to the conditional mapping

ddf

DDF in which tf is defined

tf

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

function

Function which performs the mapping @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