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.

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

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

---

 

Created with the Personal Edition of HelpNDoc: What is a Help Authoring tool?