Mapping Description String (MDS)

Back

MDS

In this page, I'll introduce what MDS stands for and how it work in DIVA.

MDS stands for the Mapping Description String.

First, you need to understand the format in MDS file. Second, I'll bring up some scenarios to help you understand why we need MDS. Last, in order to make you understand MDS in a short time, I'll address three trace entries that you can begin to trace the code in DIVA.

Definition

MDS stands for the Mapping Description String.

In DIVA, when you need to visualize a variable, you will map it to some mapping nodes in MappingDialog at first time. However, it can only take minutes, re-doing it is annoying and time consuming. You must connect so many mapping node to the ports you want, nobody want to repeat the action too many times. So we provide the save and load function in xDIVA. You can save the mapping result into a file called MDS file.

When we want to visualize an object, if there's a compatible MDS file, DIVA will reconstructs the xMappingTree from this MDS file. So you don't need to re-map the Mapping Node in MappingDialog.

Format

The first line of MDS file is the description of MDS version, which would be specified as MDS versionversion_number. The second line is the description of MDS type with the format : VARTYPE = your_type. Then, the main description of this MDS start with the BEGIN tag, and end with the END tag. In the mapping description, it divides into three parts :

1. MDS version

In this part, it describes the version of MDS. For example :

MDS version 1.1

2. node_definition

MappingEngine can read this MDS file and convert it into a xMappingTree. At beginning, MappingEngine will read the node_definition to reconstruct these mapping nodes. This block of node definition starts with node_definition { and ends with } . In this block, each line represents to a mapping node. The basic format is :

  node serial_number node_type parameter1 paramter2 ...

Each line starts with node, and a increased number, serial_number, stands for the number of the mapping node. node_type represents for the type of mapping node. Different node type has its different parsing rules, and we will discuss it in next section: Node Type Table.

3. link_definition

After we reconstruct these mapping nodes, there are still some link between them need to be constructed. In this block, it defines the connections between two mapping nodes.

This block of link definition starts with link_definition { and ends with } . In this block, each line represents a link between two mapping nodes.. The basic format is :

  node left_node_number to right_node_number port port_number

Each line represents that the left_node link to right_node on port port_number.

Here is a example of MDS file for BT_Node:

MDS version 1.1
VARTYPE = BT_Node
BEGIN
MDS version 1.1
node_definition {
 node 3 wop bool travel
 node 4 wop BT_Node* left
 node 5 wop BT_Node* right
 node 6 vm BOOL_GREEN_RED_BALL_PTVM NULL
 node 7 vm REF_LASER_RTVM NULL
 node 8 vm REF_LASER_RTVM NULL
 node 9 vm BINARY_TREE_NODE_CPVM NULL
}
link_definition {
 node 3 to 6 port 14
 node 4 to 7 port 14
 node 5 to 8 port 14
 node 6 to 9 port 14
 node 7 to 9 port 15
 node 8 to 9 port 16
} 
END

Node Type Table

MappingEngine reads the MDS file and reconstructs the mapping nodes for xMappingTree. Here we list all types of mapping nodes which can be created from the MDS file.

Each type has its parsing rule; in the following table will address the format for each type and its result.

Type	Format	Action
wop	node serial_no wop var_type short_name	Creat a xNodeType_WOP
vm	node serial_no vm vm_name inport_no defaultstring< value1 ...>	Creat a xNodeType_VM
vmcollector	node serial_no vmcollector node_type wop_name	Creat a xNodeType_vmcollector
wopcollector	node serial_no wopcollector node_type wop_name	Creat a xNodeType_wopcollector
math	node serial_no math @ your_foumula@	Creat a xNodeType_math
stingcomposer	node serial_no stringcomposer @your_string@	Creat a xNodeType_StringComposer
clock	node serial_no clock vm_name inport_no defaultstring< value1...>	Creat a xNodeType_clock
gate	node serial_no gate node_type gate_name gate_class default_value	Creat a xNodeType_gate
vmclone	node serial_no vmclone node_type wop_name	Creat a xNodeType_vmclone
composite	node serial_no composite vm_name inport_no defaultstring< value1...>	Creat a xNodeType_composite

Scenario

Javid wants to visualize the variable P in DIVA. Meanwhile, DIVA starts to request the data type of P from JDB and try to search the corresponding MDS in MappingEngine. MappingEngine finds out the MDS of P and try to reconstruct the xMappingTree from this MDS.

Trace Entry

If you want to trace the MDS in DIVA, we suggest three trace entries in the following. Before you start to trace the code in the program, make sure that you've fully understand the pseudo code in this document.

1.Initialization in MappingEngine

Mapping Engine keeps a table which records all default MDS files in DIVA. When DIVA start to execute, it will load these information into a table for user. This MDS table is declared in MappingEngine.h

// Filename: MappingEngine.h
private : 
       map<string, string> _MDStable ; // keeps all informations about MDS

When the MappingEngine is initialized, it will initializa this MDS table at first. At beginning, MappingEngine reads a file "DIVA.mds", which records all available MDS file and path. Then, it reads each MDS file sequentially. We've talked about the format of MDS file before(MDS Format).

So, each MDS can be save into a pair, <variable_type, description>; the variable_type is the key of _MDStable and the description is the value of_MDStable.

Here is the pseudo code of the initialization of MDS in MappingEngine :

MappingEngine::MappingEngine(void){
         ...
       readFile("DIVA.mds");
       //parse the file....
       while(1){
          path = read one file path;
          pair<string,string> = readMDSfile( path );
          addMDString( pair.first , pair.second );
       }
}
pair<string,string> MappingEngine::readMDSfile(string filename) {
       read File( path );
       //parse the file ...
          ...
       get the var_type from file;
       get the description from file;
          ...
       pair<string,string> mds_pair;
       mds_pair.first = vartype ;
       mds_pair.second = mdsstr ;
       return mds_pair ;
}
void MappingEngine::addMDString(string vartype, string mdstring) {
       if( no identical entry in MDS table)
               _MDStable[vartype] = mdstring ; // add to MDS table
}

• Trace steps :

1. You can set the following breakpoint on these method :
   1. MappingEngine() in MappingEngine.cpp
   2. readMDSfile(string filename) in MappingEngine.cpp
   3. addMDString(string vartype, string mdstring) in MappingEngine.cpp
2. Run DIVA, and stop at the MappingEngine's constructor

2.visualize in Command_Agent

When Minerva sends the command 'visualize P' to DIVA, DIVA will try to find the compatible MDS for this variable(if the variable type is matched). So, we need to get the variable type of P firstly. DIVA will send the message to Minerva to request the data type from JDB and send the type name back to DIVA. When DIVA gets the data type of P,TYPE1, it can look up the MDS table in MappingEngine to determine whether TYPE1 has the corresponding MDS or not. If there's a MDS mathced to TYPE1, we can create the xMappingTree from this MDS.

Here is the pseudo code of visualize in Command Agent :

//Command_Agent.cpp
WOP_Entry * Command_Agent::visualize(std::string _visualItem, WOP_Entry *parent){ 
       entry = retrieveWOP;
          ...
       if( found corresponding MDS in MappingEngine )
               create xMappingTree from MDS;
       else
               pop Mapping Dailog;
          ...
}

• Execution flow

Trace steps :

1. Set breakpoint on the following method in DIVA:
   1. visualize(string _visualItem, WOP_Entry *parent) in Command_Agent.cpp
   2. searchMDString(string vartype) in MappingEngine.cpp
   3. fromMDStoXMappingTree(string MDS, WOP_Entry *en) in xMappingTree.cpp
2. Run xDIVA, open the file RGB.java" in Minerva and set the breakpoint on line 40.
3. Press "visualize", and enter "singlecube".

3.unfoldRef in Command_Agent

Here is the pseudo code of unfoldRef in Command Agent :

//Command_Agent.cpp
WOP_Entry * Command_Agent::unfoldRef(std::string _visualItem, WOP_Entry *parent){ 
       entry = retrieve the entry you want to unfold;
         ...
       if( found corresponding MDS in MappingEngine )
               create xMappingTree from MDS;
       else
               pop Mapping Dailog;
          ...
}

1. Set breakpoint on the following method in DIVA:
   1. unfoldRef(string _visualItem, WOP_Entry *parent) in Command_Agent.cpp
   2. searchMDString(string vartype) in MappingEngine.cpp
   3. fromMDStoXMappingTree(string MDS, WOP_Entry *en) in xMappingTree.cpp
2. Run xDIVA, open the file RGB.java" in Minerva and set the breakpoint on line #40.
3. Press "visualize", and enter "singlecube".
4. In DIVA. there is a black cube. Double click on the cube, DIVA will start to unfold its content.

Relative MDS methods

In this section, we list all relative methods about the MDS. Part of codes would be rewrite in pseudo code.

1.Relative MDS methods in MappingEngine

• addMDString : add an entity of MDS to MDS table

void MappingEngine::addMDString(string vartype, string mdstring) {
       map<string, string>::iterator itr ;
       itr = _MDStable.find(vartype);
       if (itr == _MDStable.end()) {
               _MDStable[vartype] = mdstring ;
               return ;
       }
       assert(false); // in the future, we may want to allow the update of mdstring.
       return ;
}

• removeMDString : remove an entity of MDS in MDS table

void MappingEngine::removeMDString(string vartype) {
       map<string, string>::iterator itr ;
       itr = _MDStable.find(vartype);
       // Check if item exists
       if( itr != _MDStable.end() ) {
           _MDStable.erase(itr);
       }
}

• searchMDString : search a specific entity of MDS in MDS table

string MappingEngine::searchMDString(string vartype) {
       map<string, string>::iterator itr ;
       itr = _MDStable.find(vartype);
       if (itr != _MDStable.end()) {
               return itr->second ;
       }
       return "" ;
}

• SaveToMDSfile : save a MDS file

void MappingEngine::saveToMDSfile(string filename, string vartype,string mdstring) {    
       ofstream mdsfile(filename.c_str(), ios_base::out | ios_base::trunc);
       assert(mdsfile); // if file open error, quit for now
       mdsfile << "MDS version 1.1" << endl ;
       mdsfile << "VARTYPE = " << vartype << endl ;
       mdsfile << "BEGIN" << endl ;
       mdsfile << mdstring << endl ;
       mdsfile << "END" << endl ;
       mdsfile.clear();
       mdsfile.close();        
}

• readMDSfile : Input a filename and read this MDS file.

pair<string,string> MappingEngine::readMDSfile(string filename) {
       pair<string, string> mds_pair ;
       string aline,vartype, mdsstr ;
       string str[10] ; 

       ifstream mdsfile(filename.c_str(), ios_base::in) ;
       assert(mdsfile); // if file open error, quit for now 

       getline(mdsfile, aline);
       assert(aline == "MDS version 1.1") ;
       mdsfile >> str[0] >> str[1] >>    vartype ;
       assert(str[0] == "VARTYPE");
       assert(str[1] == "=" ); 

       mdsfile.ignore(1,'\n');
       getline(mdsfile, aline);
       assert(aline == "BEGIN");

       mdsstr = "" ;
       do {
               getline(mdsfile, aline);
               if (aline == "END") break ;
               mdsstr += aline + '\n' ;
       } while (1) ;</br>
       mds_pair.first = vartype ;
       mds_pair.second = mdsstr ;
       return mds_pair ;
}

2.Relative MDS methods in xMappingTree

• fromMDStoXMappingTree : This method is the most important one in xMappingTree; which convert the mapping description string into a xMappingTree. Here is the pseudo code of fromMDStoXMappingTree, please trace this method in detail.

xMappingTree xMappingTree::fromMDStoXMappingTree(string MDS, WOP_Entry *en) {
       xMappingTree xmt ;
          ...  
       tokenize(MDS);
          ...
       // read the node definition block
       while( not reach the right scope ){
               determine the type of node;
               create the corresponding xNodeType;
               parse MDS and create the xMappingNode;
               Add this xMappingNode to xmt;
       }

       // read the terminal definition block
       while( not reach the right scope) {
               get the right mapping node;
               add this terminal to xmt;
       }

       // read the link definition block
       while( not reach the right scope ){
               get the left mapping node;
               get the right mapping node;
               create the link to xmt;
       }
       return xmt ;
}

3.toMDString & parseMDString in xNodeType

xNodeType is a base class, which includes two virtual method, toMDString and parseMDString. All inheritor classes should override these two methods and implement their parsing rule.

• toMDString : Encode information to MDS-format.
• parseMDString : Parse MDS to retrieve some information.

See Also

• MappingEngine
• xMappingTree
• xNodeType