Using the Mask Merger

Merger Principles

When upgrading your server installation with a new version, changes to original mask files must be transferred to the customized ones. The batch tool processes these files for a mask name:

• The previous mask file version of the DEFAULT mask
• The current mask file version of the DEFAULT mask
• The previous mask file version of the specific mask name

File content is automatically sorted when loaded; but a node’s weight (the line offset versus its parent node) is kept to sort back the resulting tree according to the weight of added nodes in the sub trees:

• List of authorized values (VALUE)
• Ordered list of attribute use (FATTR)

Merging nodes from different trees (NEW or CUSTO) and recombining them according to their weight in the different trees, may lead to unexpected orders. For more information, see Node Reordering After Merging.

The tool builds a table listing the actions and node origins (see the information below the table for descriptions of the column values):

If the action for a node is unclear, alternate actions can be performed as defined in a rule file.

The actions for the Recommendation and Alternate columns can specify any of these:

The node origin for the Recommendation and Alternate columns can specify any of these:

The Next iteration columns define complementary actions that have to be performed:

Iteration Example

This example uses the mask files shown here, with the current iteration indicated by the red box:

Based on the table above, the current iteration situation is "Node added in Cus":

The action to be taken is "Add Cus". In this case, it is not necessary to merge sub-levels before performing the "Add Cus" action (deep first = no). The E2 node (and its sub-tree) is added to the current result. The recommended action is performed, no rule file is taken into consideration.

The current node's cursor in the CUS tree moves to the next sibling, which results in the following case at the beginning of the next iteration.

Sample

Suppose we have the following initial file content:

The values for the attribute indicate the mandatory value (Y or N) and the default value (in this case, Ref or Cus)

These steps describe the iterations taken for the above mask files:

1. Merging iterations start on the first child node of each root mask node, Entity E1 in our example. Result:
   • Situation: No Change
   • Action: KEEP CUS
   • Deep first, but no child node; continue with next sibling of REF, NEW and CUS trees.
2. Entity E2 is evaluated. Result:
   • Situation: Removed from CUS
   • Action: IGNORE NEW
   • Next sibling: REF, NEW
3. The cursor for the REF and NEW trees is at Entity E4, and the cursor for the CUS tree is at Entity E3. Result:
   • Situation: Added in CUS
   • Action: ADD CUS
   • Next sibling: CUS
4. The cursors in all trees are now at Entity E4. Result:
   • Situation: No Change
   • Action: KEEPO CUS
   • Deep first: start a new iteration process on ENTITY E4’s sub-level tree.
5. Result:
   • Situation:
   • Action:
6. The first attribute for E4 is evaluated. Result:
   • Situation: No change
   • Action: KEEP CUS
   • Deep first: start a new iteration process on ATTR A1’s sub-level tree
7. The mandatory value for Attr A1 is evaluated. Result:
   • Situation: Node value changed in NEW
   • Action: KEEP NEW
   • Deep first: No child nodes on properties level (“_”); continue with next sibling of REF, NEW and CUS trees
8. The default value for Attr A1 is evaluated. Result:
   • Situation: Node value changed in CUS
   • Action: KEEP CUS
   • Deep first: No child nodes on properties level (“_”); continue with next sibling of REF, NEW and CUS trees
9. The REF, NEW, and CUS trees at the ATTR A1 level have no more siblings. The current sub-level iteration process stops, and returns to the ENTITY E1 iteration level.
10. The REF, NEW, and CUS trees at the ENTITY E1 level have no more siblings. The current sub-level iteration process stops, and returns to the root (mask) trees iteration level.
11. The REF, NEW, and CUS trees at the root level have no more siblings. The merger process ends. The resulting mask file is:

    MASK MYCUSTO ENTITY E1 ENTITY E3 ENTITY E4 ATTR A1; Y;N;Cus

Mask Merger Syntax

The VPLMPosMaskMerger server-side batch (Windows) or shell (UNIX) command is located in:

• INSTALL_PATH\server\win_b64\code\command (on Windows)
• INSTALL_PATH/server/scripts (on UNIX)

The mask merger merges all mask files listed in the previous customization directory of each specified mask name (<previous_custo_dir>/vplm/mask/<mask_name>). Each merged file is generated in a subdirectory of the output directory, based on the mask name (<output_dir>/vplm/mask/<mask_name>). If a subdirectory does not exist, the tool creates it. The merger does not use the PLM Dictionary to make additional checks (for example, checking if an entity really exists). It only requires mask files to have a correct mask file syntax.

After running the mask merger, you need to recompile the mask files. For more information, see VPLMPosMaskCompiler.

The syntax is as follows:

VPLMPosMaskMerger		[-h]
         -m	<mask_name> [<mask_name> ...]
         -p	<previous_DEFAULT_dir> <current_DEFAULT_dir> [<previous_custo_dir>]
         [-d <output_dir>]

Node Reordering After Merging

Some nodes have to be resorted according to their original appearance order. This is the case for authorized values (VALUE) and attributes use in function (FATTR). The resulting nodes may come from different trees (NEW or CUSTO), and their weight in their original tree from may not coincide in the resulting tree. Recombining them according to this weight (plus the alphabetical order if weights are the same) may lead to unexpected orders, although this is a normal behavior.

Here is a small example:

The order (One, Many, Two) may seem inappropriate (a logical order would have been : One - Two - Many), however:

• One and Many come from the CUS tree; they kept their respective original order such that Many (weight=1) appears after One (weight=0).
• Two comes from the NEW tree, with the same weight as Many (=1). As Many"" is alphabetically lower than "Two", it appears finally before "Two".