Sequences
As mentioned before, the general mapping rule is "for each item in the source, create one in the target". Here, "item" means one of the following:
•a single instance node of the input file or database
•a sequence of zero to multiple instance nodes of the input file or database
During mapping execution, if a sequence reaches a target item, this creates a loop that generates as many target nodes as there are source nodes. There are some exceptions to this rule, however:
•If the target item is an XML root element, it is created once and only once. If you connect a sequence to it, the result might not be schema valid. If attributes of the root element are also connected, the XML serialization will fail at mapping runtime. Therefore, avoid connecting a sequence to the root XML element.
•If the target item accepts only one value, it is created only once. Examples of items that accept only one value: XML attributes, database fields, simple output components. For example, the mapping below generates a sequence of three integers (1, 2, 3) with the help of the generate-sequence function. Nevertheless, the output will contain only one integer, because the target is a simple output component that accepts a single value. The other two values are ignored.
•If the source schema specifies that a specific item occurs only once, but the instance file contains many, MapForce may extract the first item from the source (which must exist according to the schema) and create only one item in the target. To disable this behavior, clear the check box Enable input processing optimizations based on min/maxOccurs from the component settings, see also XML Component Settings.
If the sequence is empty, nothing is generated on the target side. For example, if the target is an XML document and the source sequence is empty, no XML elements would be created in the target at all.
Functions work in a similar way: if they get a sequence as input, then they are called as many times as (and produce as many results as) there are items in the sequence.
If a function gets an empty sequence as input, it returns an empty result as well, and consequently produces no output at all. |
However, there are some categories of functions that, by virtue of their design, return a value even if they get an empty sequence as input:
•exists, not-exists, substitute-missing
•is-null, is-not-null, substitute-null (these three functions are aliases of the previous three)
•aggregate functions (sum, count, and so on)
•user-defined functions that accept sequences and are regular (not inlined) functions
If you need to replace an empty value, add the substitute-missing function to the mapping and replace the empty value with a substitute value of choice.
Functions may have multiple inputs. If a sequence is connected to each input, this produces a Cartesian product of all inputs, which is typically not the desired outcome. To avoid this, connect only one sequence to a function with multiple parameters; all other parameters must be connected to "singular" items from parents or other components.