Synopsis

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

Purpose

Enable a mapping, mapping list, or conditional mapping.

Description

The mapping specified by name will be enabled. When the map_DispatchEntity function encounters an entity of the type associated with the mapping name, the appropriate mapping function will be invoked. The mapping must first be defined using map_DefineMapping, map_DefineConditionalMapping, or map_DefineMappingList. Multiple mappings can be enabled for a given DTF by calling this function with each mapping to be applied. The mappings will be applied in the order they are enabled in. If the MAP_CLEAR_DTF option is specified, all mappings already enabled for the DTF associated with the mapping will first be removed.

If the mapping being enabled was defined with a wildcarded form (see map_DefineMapping), the mapping will be individually enabled for each form of the entity type. To clear the resulting mappings, map_ClearDTF must be called for each form of the entity.

Following the mapping name is a variable argument list of additional information to be used with the mapping. This list is in the form of tokenized name/value pairs. The list is terminated with MAP_END for the token. The MAP_END token must be present, even if no additional arguments are specified. The allowable token types and their corresponding values are listed below:

.IP MAP_PARAM 12 The following argument is a parameter name and value for the mapping. If the mapping being enabled is a mapping list, the parameters will be duplicated for each mapping in the list (so calling map_GetParameter with any mapping in the list will return the same parameter value).

.IP MAP_MODEL The following argument is an integer containing the model number in which the results of this mapping are to be placed. It is assumed that the model is of a type appropriate for the results of the mapping (e.g. a GDX model if the mapping results in a GDX entity). If this parameter is not specified, the model that the resulting entities will be created in depends on whether the DDF for the input entities is the same as the DDF for the output entities. If it is, the entities will be created in the same model as the source entity. If not, the resulting entities will be created in the first model with the type of DDF that was specified in the map_DefineMapping call. If the mapping being enabled is actually a mapping list, the model specified will be used only for the final results of the mapping list. All intermediate mappings will use the default model as described above.

.IP MAP_COMMIT The results of the mapping should be made permanent rather than being deleted after the mapping is complete. This token does not accept a value. If this token is specified, the results of the mapping are not passed to the application dispatcher or back into map_DispatchEntity. Note that if this token is specified and there is more than one model allocated with the target DDF of this mapping, the application should explicitly set the output model with the MAP_MODEL token to ensure that the output entities are committed to the correct model. If the mapping being enabled is actually a mapping list, only the entities generated by the last mapping in the mapping list will be committed.

.IP MAP_END Indicates the end of the additional arguments. This must be present even if no other tokens were specified. .LP A simple call to map_EnableMapping is shown below:

.nf map_EnableMapping (MAP_NOOPT, table, "sample map", MAP_END); .fi

An example call to map_EnableMapping with each of token types is shown below:

.nf map_EnableMapping (MAP_NOOPT, table, "sample map", MAP_MODEL, target_model, MAP_PARAM, ASYS_PARM1, 1.0, MAP_PARAM, ASYS_PARM2, PDX_TRUE, MAP_COMMIT, MAP_END); .fi

If the MAP_STRING_ARGS option is specified, then the variable arguments consist of a single character string with the additional parameters embedded in it. The list of additional arguments is specified exactly as described above except for the MAP_MODEL token. When embedded in a string, the model value is specified as a single quoted string containing the name of the model (as assigned in the model_info structure passed to mda_AllocateModel) rather than the model number. The MAP_MODEL, MAP_PARAM, MAP_COMMIT and MAP_END tokens may also be abbreviated as MODEL, PARAM, COMMIT, and END within the string. Parameter values for boolean type parameters may be specified as either an integer or a character string "true" or "false" (without the quotes). The argument string is case sensitive. The MAP_END token is optional if the MAP_STRING_ARGS option is used. The MAP_END token is also optional in the argument string.

When specified as a string, the arguments may be separated by commas, spaces, tabs, or newlines.

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_EnableMapping (MAP_STRING_ARGS, table, "sample map", "MAP_MODEL, 'target_model'," \ "MAP_PARAM, ASYS_PARM1, 1.0," \ "MAP_PARAM, ASYS_PARM2, true," \ "MAP_COMMIT"); .fi

Input

option

MAP_CLEAR_DTF

Clears all mappings already enabled for the DTF associated with name

MAP_STRING_ARGS

Additional arguments are specified as a character string rather than individual arguments.

table

Mapping table to name is defined in

name

Mapping to be enabled @a ... List of additional arguments terminated with MAP_END or a single character string containing the additional arguments if MAP_STRING_ARGS is set.

Return

MAP error code