File IO / Database
Block Name: Database

Code File Location: VisualSim/actor/lib/Database

Block Overview

  o Used as a lookup table for doing searches.  

  o Examples of usage include routing table, lookup values to match certain attributes like disk drive zone and speed.  

  o Cmpares up to 6 fields of the input transaction with 6 columns in the database. 

  o Database content is available for viewing and processing using the RegEx functions.

Description

This block is a lookup table or database containing rows and columns. Each row is a data structure. Each column of the row is a field of the data structure. For every input, the block matches upto 6 fields of the incoming Data Structure and with matching 6 columns of the Table. The following are the main features of the Database block:

Three functions- Read, Write and Erase

• Read- You have an incoming request and you want to match with the database.
• Write- If a row matches in the database, replace. If the row does not exist, append.
• Erase- If a row matches, erase that row.

Match format:

• Send out the matched row: output = match
• Send out a single column value in that row: output = match.A_Hop
  
• Append/replace a value to the input transaction and send that one out: output = input.A_Hop
  
• RegEx with the input transaction and send out the computed value: output = input.A_Hop + match.A_Hop

Types of matches:

• match- Sends out the first match. The output format is either a data structure (if the matched line or appended input) or a unique data type (all types supported)
  
• match_all- Sends out all the rows that match.  The form will be an array of transactions (if the matched line or appended input) or an array of unique data type (all types supported).
  
• match_all is only applicable for Read operation
  

Database content entry:

• In a model, a single Database block can have the content defined. This block will have a 'linking_name'.  All other database blocks that will use this content will have the same 'linking_name' and enter 'extern' in the Data_Structure_Text.
• The items in the Database can be of any data type. 
  
• Items can be a calulation containing Parameters and scalar values.  Any computed values must be within parathesis ().

Points to note:

• The Database must contain the Header row and at least one row of data. The single row of data is required to define the data type for each column. 
  
• The Database block always requires a data structure on the input port

File Name: This block accepts a file name as a parameter. There are a number of file path options available for this block.  To see the list, view the section on File Paths in the Reference Guide document here. The file name is a concatenation of any number of individual strings and parameters, separated by "+".  To view the file path in a demo model, click  here.

• Look at the  Match ALL Rows Example in the BDE.

Other Features

1. The content of the Database can be accessed as an  array of data structures from any ExpressionList or Script blocks.  The name of the memory is the Linking_Name.
2. Multiple database blocks can reference a single database for the content.  In this case, the text window has an extern for all the one's that are referring to a single database block.  In this case, all these database blocks read/write/remove this single database.  The content is instantly updated in all the Database blocks.
3. When conducting a Write operation, the field name and number of fields in the Database must match the incoming Data Structure, else a exception will be reported.  The header fields of the incoming Data Structure are ignored and not updated in the Table.
4. If the Linking_Name is either set to "Default" or "None", then the database does not link to any other database block and cannot be accessed from the script code.

Block Operation

1. The initial content of the database block can be provided in 4 formats-  Text Window,  CSV file,  TXT file  and   XML file.  Click on the links to see the file formats.
Sample Lookup table Syntax for csv and txt files:
  a) for TXT format,
             ID  MyStr  MyInt  MyDbl  ;    
             0    "Str_1"    1        1.0   ;
             1    "Str_2"    2        2.0   ;
             2    "Str_3"    3        3.0   ;
             0    "Str_4"    1        4.0   ;
             1    "Str_5"    2        5.0   ;

b) for CSV format,
            ID,MyStr,MyInt,MyDbl
             int,string,int,double   
             0,Str_1,1,1.0 

                       1,Str_2,2,2.0  
                       2,Str_3,3,3.0  
                       0,Str_4,1,4.0  
                       1,Str_5,2,5.0 

2. The Data_Structure_Text can refer to the xml, txt or csv file in the following different formats.  Click on examples provided for the  xml file,  txt file and  csv file file entry format.

3. The first row will contain the names of the columns.
4. Maximum number of rows for simulation performance is about 4000.  
5. There must be equal number of fields in 'Input_Fields' and 'Lookup_Fields'.  The first 'Input_Fields'  name is matched with the first 'Lookup_Fields' name and so on.  The matching fields can be of type integer, long, double, string, and boolean.
Note: Maximum Limit of Input_Fields and Lookup_Fields is 6.

RegEx Function:

       The Database table data can be access and processed using the RegEx utility function that is described below.  RegEx Example

The block has 5 utility functions that can access the Database table from anywhere in the model and at any time during the simulation.

Function 1:

 getColumn (String database_name, String column_name)

 Eg: Result_A = getColumn("Linking_1","dest")

Output:
        {"0", "0", "1", "2"}
Description: This function is used to get an Array of Column entries from Database block. This output the column name as an Array .

Function 2:

 getNextResource (String database_name, String column_name)

 Eg: Result_A = getNextResource("Linking_1","dest")

Output:
        "Processor_1"

Description: This function is used to get the item in the next row in a column from the Database block. The Return type should be based on the Datatype exists in the table.

Function 3:

 getResourceActivity (String database_name, String column_name) 

 Eg: Result_A = getResourceActivity("Linking_1","dest")

Output:
         {Resource_Name, Resource_Length, Resource_Name, Resource_Length,.... Resource_Name, Resource_Length}

        {"0", "9", "0", "9", "1", "0", "2", "0"}

Description: This function is used to get an Array of Resource Activity from Database block, based on Column Name,  returned as an Array. Assumes all column named resources exist in the model and can be accessed.  Method supports Processor, SystemResource, SystemResource_Extend blocks. With one RegEx command user can get current queue length of a column of named resources as an array.  Processor and other hardware blocks use "Architecture_Name.Processor_Name"format.

Function 4:

getRows (String database_name, String row_name, String column_name) 

 Eg: Result_A = getRows("Linking_1","1","dest")

Output:

{{BLOCK                = "Database3",
   DELTA                  = 0.0,
   DS_NAME            = "DS_Database3",
   ID                           = 0,
   INDEX                   = 0,
   TIME                     = 0.0,
   dest                        = "0",
   hop                        = 5,
   sequence                = 0,
   source                    = "0"}, {BLOCK                = "Database3",
   DELTA                  = 0.0,
   DS_NAME            = "DS_Database3",
   ID                          = 1,
   INDEX                  = 0,
   TIME                     = 0.0,
   dest                        = "0",
   hop                        = 6,
   sequence                = 0,
   source                    = "1"}}

Description: This function looks for each row_name that matches what is in the column. If column_name equals "Destination", and row_name equals "Node_1", then this method returns all rows as Data Structure with the "Destination" column equal to "Node_1" as an Array.  This is handy for obtaining additional information for this destination, either in terms of routing, or data size/rates.

Function 5:

getRows (String database_name, String row_name, String column_name, String row_name2, String column_name2)

 Eg: Result_A = getRows("Linking_1","0","dest","3","source")

Output:

{{BLOCK              = "Database3",
   DELTA                = 0.0,
   DS_NAME          = "DS_Database3",
   ID                         = 2,
   INDEX                 = 0,
   TIME                    = 0.0,
   dest                       = "1",
   hop                       = 7,
   sequence               = 0,
   source                   = "3"}}

Description: This function looks for multiple match between rows and column. If column_name equals "Source", and row_name equals "Node_1", column_name2 equals "Destination", and row_name equals "Node_2", then this method returns all rows as Data Structure with the "Source" column equal to "Node_1", "Destination" column equal to "Node_2" as an Array.  This is handy for obtaining additional information for routing (multiple paths), or data size/rates.

Function 6:

getCell(String database_name, String row_name, String column_name)

 Eg: Result_A = getRows("Linking_1","FFT","Instruction")

Output:

{"ADD","LD_LDR","MUL","MOV"}

Description: Note that this function works only if the database contains a coulmn named Task_Name, which will be unique for each row. So when using Row_Name in the getCell function, what happens is that we look into the row which is having Task_Name as the Task_Name specified. Once we have the row selected, then we check the third argument mentioned in the getCell () and gets that coulmn value. This function is usefull if we only want a particular value rather than an array of values as with the case for other functions related to the database.

Demo Model

    To illustrate the usage, look at the following examples in the Block Diagram Editor.
Database and Lookup Example
File Access Example
Read Mode
Write Mode
Remove Mode
RegEx Example
Expression on Output Expression Parameter Example

Parameter	Explanation	Type	Example
Linking_Name	This is an unique memory name for this block. This is an optional field and is required when multiple database blocks need to reference this block for the content or the content of this database will be used in an Expression. This name is used to link multiple Database blocks that need to use the same lookup table. If this field is set to "None", or left to default, then no linking with other Database blocks. All blocks using the same lookup table must have the same linking name. The main block will have the Data_Structure_Text defined while all the referring blocks will have the 'Data_Structure_Text' parameter set to "extern".	String	"Linking_Name_or_None"
fileOrURL	The name of the file containing the table. The format can be .csv, .txt or .xml.  There are a number of file path options available.  To see the list, view the section on File Paths in the Basic technology document here. The file name is a concatenation of any number of individual strings and parameters, separated by "+".  To view the file path in a demo model, click  here.	String	FileSelector
Data_Structure_Text	The content can be placed directly in the window, in a file (TXT or CSV) or a reference to another database block (extern). Content in Window: This window can contain the lookup table in the format below. The text-based entry should enter the field names in the first row. File Name: This block accepts a file name as a parameter. There are a number of file path options available for this block.  To see the list, view the section on File Paths in the Basic technology document here. The file name is a concatenation of any number of individual strings and parameters, separated by "+".  To view the file path in a demo model, click  here.	String	ID MyStr MyInt MyDbl 0  Str_1   1   1.0  1  Str_2   2   2.0  2  Str_3   3   3.0  3  Str_4   4   4.0  4  Str_5   5   5.0
Input_Fields	This is a list of fields in the incoming data structure. The values in these fields are matched with the respective list in the index fields (Lookup_Fields) of the Database. There can be a maximum of Six fields in a comma separated format. The match is between the first in the Input_Field with first in the Lookup_Field, second in the Input_Field with second in the Lookup_Field,and so, on. All fields have to match.	String	"Fld_Name_1, Fld_Name_2, Fld_Name_3.."
Lookup_Fields	This is a list of column names in the database. The values in these columns are matched with the respective list in the fields of the incoming data structure (Input_Fields) of the Database. There can be a maximum of Six fields in a comma separated format. The match is between the first in the Input_Field with first in the Lookup_Field, second in the Input_Field with second in the Lookup_Field,and so, on. All fields have to match. 'Input_Fields' must match 'Lookup_Fields' in length and type.	String	"Fld_Name_A, Fld_Name_B, Fld_Name_C.."
Output_Expression	Parameter that specifies the match type and the value to be placed on the output port. The match type and the expression are combined in this field. The match keywords are: match,and match_all. The match_all produces an array of data structures, where each is a matching row. match outputs a single data structure. In addition to the standard data structure output, this block can output a field of the selected data structure or the result of a regular Expression that contains any combination of the matched row fields, input data structure and an expression. match_all works only with read operation	String	"output = match" /* FORMAT output = match.fieldb */ o If a full data structure is to be sent out, then the default value in the Expression field "output = match". o If a field of the selected Data Structure is to be sent out, then the format will be "output = match.field_a". o If the result of an Expression, then the format will be "output = match.field_a * match.field_b + (Regular Expression operation). The Expresion language can use all the fields of the selected row and the input Data structure in the Expression. Example Model o Keywords "match_all" can also be used in place of "match".  The “match_all” will output an array of Data Structures that were matched. o The block will solve the entire RHS as an expression and then place the result value on the output port.
Mode	This parameter specifies if this block instance is used lookup (Read), write incoming Data Structures (Write) or delete (Remove). This is a string-valued attribute that defaults to "Read". Read Mode: o match: output the single matched row. o match_all: ouput all the matched row (multiple match)              Write Mode: o The Write mode can either overwrite a matched row or append a new line. Remove Mode: o match: remove a single matched row	String	Read, Write, Remove

Port	Explanation	Type
input	The Data Structure containing the fields that is matched against the Lookup table Index field.	General
output	The result of the output_expression is sent on the output port.	General
exception	The exception port sends the requesting Data Structure to this port if a match cannot be found for the "Read" and "Remove" operations.	General

Note: Database block have no impact on newly added input and output port.

---