mark for future value()

This function places a marker a on a target field. Later this marker can be replaced with an actual value with function replace marked value().

Marking and replacing only works within a record. With the start of a new record, the markings are removed and replaced with an Empty Flag.

It is recommended not to use the function in a function chain, but to place it alone on a field. If the field is used as a sorting field of a node, the sorting takes place after the substitution with the actual value.

Parameters


Parameter

Description

a

Name of the marker.

Example


The input file below


order.txt
H;Sender;Receiver;2011-10-21;20:06:32
P;10000;200;Article 1
P;20000;100;Article 2
P;30000;500;Article 3


will be mapped to the following XML structure (reduced to the part being relevant for this example).


images/download/attachments/189442817/732-version-1-modificationdate-1734504499314-api-v2.png


The header should contain - among other things - the total number of positions following it. This information is not available at the moment. One solution could be another node at the beginning of the tree iterating over the positions and increasing a counter. Because the mapping is already doing this at a later point in time when creating the positions in the output tree, the functionality of this function comes into place. NumberPositions uses this function with the marker value MARK_POSCOUNT:


1) mark for future value(a)
a constant: MARK_POSCOUNT


The calculation field increaseCounter increases a variable POSITION_COUNTER by one every time, the node is entered (i.e. a new position is created).


1) calculate and save variable(a,b,c,d,[e])
a constant: POSITION_COUNTER
b constant: +
c constant: 1
d constant:
e constant:


Finally, the calculation field setNumberPositions let all fields being marked with MARK_POSCOUNT be set with the value of the variable POSITION_COUNTER.


1) replace marked value(a,b)
a constant: MARK_POSCOUNT
b variable: POSITION_COUNTER


In an example like this, the difference in runtime between the two approaches is minimal. However, the more positions have to be processed, the larger the difference will be.

Using future values


It is possible to use values that are only calculated in the future. This can be done with the aid of two functions.

Create a new profile


images/download/attachments/189442817/882-version-1-modificationdate-1734504840564-api-v2.png


First, we create a simple CSV mapping profile (line separator NL and field separator semicolon), containing a source structure for a header record and several item records. Additionally, we want to calculate the number of items and show it in the target structure field number_of_items. Following our simple input data.


H;4711;Lobster
I;A-1;Article 1
I;A-2;Article 2
I;A-3;Article 3


Please use the record match code H for the header node and I for the item node. If you have finished the source structure, you can simply create the target structure by clicking on the 1:1 button. The only thing left to do now is to create the target field number_of_items in node Header and the calculation field calc_number_items in node Item.

Create variable


Create a new variable of type Integer and the name var__COUNT_ITEMS.

Calculate number of items


images/download/attachments/189442817/880-version-1-modificationdate-1734504840754-api-v2.png


Use the function "calculate and save variable()" on calculation field "calc_number_items" and set it like in the screenshot above. This will increment the variable "var__COUNT_ITEMS" for each iteration of node "Item" by "1".

Write number of items in header record


images/download/attachments/189442817/883-version-1-modificationdate-1734504840773-api-v2.png


To be able to write the final value of variable var__COUNT_ITEMS in field number_of_items, we need to use the function "mark for future value(a)".

What is happening here?

The node Header is processed before the node Item. At this point in time, we do not have the final value of variable var__COUNT_ITEMS. For that reason, we use the 'future value' item_counter in field number_of_items.

Write number of items


images/download/attachments/189442817/884-version-1-modificationdate-1734504840784-api-v2.png


To fill the 'future value' item_counter, after all the items have been processed, we create a new node (below node Item) with a calculation field fill_marked_field. This field uses the function "replace marked value(a,b)".

What is happening here?

Node End is processed at the end of the mapping. The function "replace marked value(a,b)" replaces the 'future value' item_counter with the final value of variable var__COUNT_ITEMS (parameter b).

Test


images/download/attachments/189442817/881-version-1-modificationdate-1734504840796-api-v2.png

If you did everything correctly, a test should show you the result shown in the screenshot above.

The following is not possible


  • The use of target fields using the function mark for future value(a) as parameters in functions is prevented to avoid complex backtracking.

  • Replacements are only done in the current record! Values cannot be replaced over several records.

Empty values

If function "replace marked value()" is not executed, the Empty Flag is set for field "number_of_items".

Example profile


Profile-Future_values.pak