This function is an expert function! Please use function add to "map()" in standard cases.

It adds the value b to the key a in the map named c on level d of an inheritance value. If the string representation of value b matches the regular expression e, then the value gets the Empty Flag).

Note: The return value is the value in b. If the logic in e sets the empty flag, the return value also gets an empty flag (even if the value b did not have an empty flag originally)!

When calling this function, the value that was located in the named map c in relation to key a is changed into multi-level inheritance value. The present value is thus transferred to level 1 (root) of the inheritance value. In addition, further values related to key a can now be saved in level 2, 3, … . If a value without Empty Flag is saved to a higher level, then the values of the lower levels will be hidden. The value visible is the one in the foreground (on the highest level).

The function "get value from map()", for example, will only return the visible single value with the highest level (see Inheritance Values). The function "remove from map()" removes the complete multi-level inheritance value, but only its visible value is returned. If all levels are empty or contain only values with a set Empty Flag, then the visible single value is a string of length 0 ("") with set Empty Flag.

Parameters

Parameter	Description
a	Key value.
b	Value to be added.
c	Name of the map.
d	(optional) Level. Default: 1.
e	Regular expression that triggers the setting of the Empty Flag for the value under key a at level d. If the value should not be interpreted as a regular expression but instead as literal value, the value must be surrounded by \Q and \E.

Examples

An EDIFACT or an IDoc document can contain certain information either in the header or in the items. There might also be a default value in case neither the header nor the positions contain a value. The following rules apply.

If an item contains a value, the item value counts. In that case, an existing header value is not used.
If an item does not contain a value, the corresponding header value is used.
If there is no header value either, the default value is used.

In scenarios like this, we can use this function here to avoid branched function chains (with "goto" functions). Instead, every document level is associated with a corresponding level of an inheritance map. Higher levels cover all lower levels. The function "get value from map()" returns the value of the highest visible map level (see below). We will use the following association.

Raw data level	Description	Map level
Initialisation/Job level.	Process default/System default.	1
Record/Document level.	Specification in document (e.g. selected customers).	2
Header node/Header level.	Specification in the message header (e.g. shipment).	3
Item node/Item level.	Specification in item (e.g. article or package).	4
Subitem node/Subitem level.	Specification in subitem (e.g. lot/subset).	5

The map levels are not associated with fixed meanings (you define the meaning of each level for yourself). Instead, level 2 'beats' level 1, level 3 'beats' level 2. In simple words: The highest level wins. The weakest level is level 1 and the strongest is level 20.

Levels you did not assign values to or assigned a value with Empty Flag to are interpreted as 'transparent' or non-existent. A lower level can be covered by a higher level. If the higher level later gets a value with Empty Flag assigned, the lower level becomes 'visible', since the higher level becomes 'transparent' (for details see the description of Inheritance Values).

Example 1

An invoice needs to have a payment date. The date of an invoice is the date when the job is processed and the invoice is sent. The shipment contains part shipments. We use a default value for the payment date but it can also be specified at the header level. Additionally, part shipments can have a different payment date.

1) The init node of the profile calculates the payment date by adding 14 days to the date of system variable VAR_TIMESTAMP and adds it to a map with function "add to inheritance-map()" with key a = ZAHLG and level 1.

2) While processing the invoice header, the profile uses the customer number to query a database to see if there is a differing payment date to be used for this customer. The differing date (or a value with Empty Flag if there is none) is added to the map with the same key but on level 2.

3) While calculating the sum of each part shipment, we validate whether the respective part shipment has a differing payment date. If it has one, it is added (or the Empty Flag is set if there is none) to the map on level 4 with the same key.

Now, for each (part) shipment sum, the payment date is read from the map with key a = ZAHLG. If on the item level (part shipment, level 4) a value with Empty Flag was added, this level will be 'transparent'. That means we will get the customer-specific payment date or, in case the customer-specific payment date has an Empty Flag as well, the default payment date.

Advantage: On the header level, you only need to implement the rules for the header level, on the item level, you only need to implement the rules for the items and in the init node, you only have to specify the default value. This makes the implementation easier to understand.

Example 2

An ORDERS IDoc containing 12 items defines a delivery address (consignee CON) at the header level. Two items have differing delivery addresses (consignee CON) at the item level.

1) While processing the header data, the delivery address defined at the header level is added to the map with key CON at level 1.

2) While processing the item data, the differing address at the item level is added to the map with the same key CON but at level 2. If there is no differing address, the Empty Flag is set.

3) Finally, we use key CON to get our value from the map. If there had been a differing address at level 2, we will get that address, otherwise, we will get the address of level 1 as return value.

Since the map can save an inheritance value with multiple levels for every key (each address qualifier), this logic can be used for all address types in the same map. Analogously, we can use a map to deal with all the date information.