Please enable JavaScript to view this site.

Altova MapForce 2020 Enterprise Edition

Designing Mappings > Using Variables

Changing the Context and Scope of Variables

Scroll Home Prev Top Next More

Every variable has a compute-when input item which allows you to control the scope of the variable; in other words, when and how often the variable value is computed when the mapping is executed. You do not have to connect this input in many cases, but it can be essential to override the default context, or to optimize the mapping performance.


The "compute-when" item

In the following text, a subtree means the set of an item/node in a target component and all of its descendants, for example, a <Person> element with its <FirstName> and <LastName> child elements.


A variable value means the data that is available at the output side of the variable component.


For simple variables, it is a sequence of atomic values that have the datatype specified in the component properties.

For complex variables, it is a sequence of root nodes (of the type specified in the component properties), each one including all its descendant nodes.


The sequence of atomic values (or nodes) may contain one or even zero elements. This depends on what is connected to the input side of the variable, and to any parent items in the source and target components.


"Compute-when" is not connected (default)

If the compute-when input item is not connected (to an output node of a source component), the variable value is computed whenever it is first used in a target subtree (either directly via a connector from the variable component to a node in the target component, or indirectly via functions). The same variable value is also used for all target child nodes inside the subtree.


The actual variable value depends on any connections between parent items of the source and target components.


This default behavior is the same as that of complex outputs of regular user-defined functions and Web service function calls.


If the variable output is connected to multiple unrelated target nodes, the variable value is computed separately for each of them. This can produce different results in each case, because different parent connections influence the context in which the variable's value is evaluated.


"Compute-when" is connected

By connecting an output connector of a source component to compute-when, the variable is computed whenever that source item is first used in a target subtree.


The variable actually acts as if it were a child item of the item connected to compute-when. This makes it possible to bind the variable to a specific source item. That is, at runtime the variable is re-evaluated whenever a new item is read from the sequence in the source component. This relates to the general rule governing connections in MapForce: "for each source item, create one target item". With compute-when, it means "for each source item, compute the variable value" (see Mapping Rules and Strategies).



If necessary, you can choose to compute the variable value once before each of the target components, making the variable essentially a global constant for the rest of the mapping. To do this, right-click the compute-when item and select Compute Once from the context menu:


When you change the scope of a variable to compute-when=once, the input connector is removed from the compute-when item, since such a variable is only evaluated once.


In a user-defined function, the compute-when=once variable is evaluated each time the function is called, before the actual function result is evaluated.



Adding a parent-context may be necessary, for example, if your mapping uses multiple filters and you need an additional parent node to iterate over, see also Example: Changing the Parent Context.


To add a parent-context to a variable, right-click the root node (in this example, "PersonList") and select Add Parent Context from the context menu. This adds a new node, parent-context, to the existing hierarchy.



The parent context adds a virtual "parent" node to the hierarchy within the component. This allows you to iterate over an additional node in the same, or in a different source component.

© 2020 Altova GmbH