Using Force Elements During Mapping Rule Activation and Deactivation
In order to provide hooks directly into the mapping rules, There are force elements which allow you to evaluate an expression when a mapping rule is activated, deactivated or both. The force element also provides a way to halt execution of the translation. While the expression evaluated will not be used, some expressions have side effects (such as logging, or arbitrary Tcl scripts) which will only be activated when the expression is evaluated.
The force element must be an immediate child of the mapping element. There are four possible attributes:
- onActivation: the legal values are “true” or “false”
- onDeactivation: the legal values are “true” or “false”
- halt: the legal values are “true” or “false”
- halt-on: where the legal value is any, including the empty, string
The halt attribute defaults to false if it is not specified.
The onActivation and onDeactivation attributes specify when the contained expression should be evaluated. At least one of onActivation or onDeactivation must be set to ‘true’ or the expression will not be evaluated. It is possible to specify that an expression be evaluated both when the mapping rule is activated and when it is deactivated. This is often useful when combined with the <logexpr> element (discussed later) to determine when various mapping rules match.
There is no default values for the halt-on attribute, this attribute provides the ability for a <force> element to conditionally halt the xfMap. The attribute will cause the xfMap to halt, if it is present and the expression sequence within the <force> element evaluates exactly to the string set on the halt-on attribute.
The following example will halt the reader when a <Tablet> element is matched, the message “’Tablet’ – is not supported” will also be printed as an error to the FME logfile.
<mapping match=”Tablet”>
<force onActivation=”true” halt=”true”>
<logexpr severity=”error”>
<arg>
<literal expr=”’”/>
<matched expr=”qname”/>
<literal expr=”’ – is not supported“/>
</arg>
</logexpr>
</force>
...
</mapping>