Store Data in Dictionary Programmatically

A data dictionary stores Simulink^® model data and offers more data management features than the MATLAB^® base workspace or the model workspace (see What Is a Data Dictionary?). To interact with the data in a dictionary programmatically:

Create a Simulink.data.Dictionary object that represents the target dictionary.
Create a Simulink.data.dictionary.Section object that represents the target section, for example the Design Data section. Use the object to interact with the entries stored in the section and to add entries.
Optionally, create Simulink.data.dictionary.Entry objects that each represent an entry in the target section. Use these objects to interact with individual entries in the target section.

To programmatically access variables for the purpose of sweeping block parameter values, consider using Simulink.SimulationInput objects instead of modifying the variables through the programmatic interface of the data dictionary. See Optimize, Estimate, and Sweep Block Parameter Values.

To programmatically interact with the Embedded Coder section of a data dictionary, see Create Code Definitions Programmatically (Embedded Coder).

Add Entry to Design Data Section of Data Dictionary

Represent the Design Data section of the data dictionary myDictionary_ex_API.sldd with a Simulink.data.dictionary.Section object named dDataSectObj.
```
myDictionaryObj = ...
Simulink.data.dictionary.open('myDictionary_ex_API.sldd');
dDataSectObj = getSection(myDictionaryObj,'Design Data');
```
Add an entry to the Design Data section of myDictionary_ex_API.sldd an entry myNewEntry with value 237.
```
addEntry(dDataSectObj,'myNewEntry',237)
```

Rename Data Dictionary Entry

Rename an entry in the Design Data, Configurations, or Other Data section of a data dictionary.

Represent the data dictionary entry fuelFlow with a Simulink.data.dictionary.Entry object named fuelFlowObj. fuelFlow is defined in the data dictionary myDictionary_ex_API.sldd.
```
myDictionaryObj = Simulink.data.dictionary.open('myDictionary_ex_API.sldd');
dDataSectObj = getSection(myDictionaryObj,'Design Data');
fuelFlowObj = getEntry(dDataSectObj,'fuelFlow');
```
Rename the data dictionary entry.
```
fuelFlowObj.Name = 'fuelFlowNew';
```

Increment Value of Data Dictionary Entry

Represent the data dictionary entry fuelFlow with a Simulink.data.dictionary.Entry object named fuelFlowObj. fuelFlow is defined in the data dictionary myDictionary_ex_API.sldd.
```
myDictionaryObj = Simulink.data.dictionary.open('myDictionary_ex_API.sldd');
dDataSectObj = getSection(myDictionaryObj,'Design Data');
fuelFlowObj = getEntry(dDataSectObj,'fuelFlow');
```
Store the value of the target entry in a temporary variable. Increment the value of the temporary variable by one.
```
temp = getValue(fuelFlowObj);
temp = temp+1;
```
Set the value of the target entry by using the temporary variable.
```
setValue(fuelFlowObj,temp)
```

Data Dictionary Management

Use Simulink.data.Dictionary objects to interact with entire data dictionaries.

Goal	Use
Represent existing data dictionary with `Simulink.data.Dictionary` object	`Simulink.data.dictionary.open`
Create and represent data dictionary with `Simulink.data.Dictionary` object	`Simulink.data.dictionary.create`
Interact with data dictionary	`Simulink.data.Dictionary` class
Import variables to data dictionary from MATLAB base workspace	`importFromBaseWorkspace` method
Add reference dictionary to a data dictionary	`addDataSource` method
Remove reference dictionary from a data dictionary	`removeDataSource` method
Save changes to data dictionary	`saveChanges` method
Discard changes to data dictionary	`discardChanges` method
View a list of entries stored in data dictionary	`listEntry` method
Import enumerated type definitions to data dictionary	`importEnumTypes` method
Return file name and path of data dictionary	`filepath` method
Show data dictionary in Model Explorer window	`show` method
Hide data dictionary from Model Explorer window	`hide` method
Close connection between data dictionary and `Simulink.data.Dictionary` object	`close` method
Identify data dictionaries that are open	`Simulink.data.dictionary.getOpenDictionaryPaths`
Close all connections to all open data dictionaries	`Simulink.data.dictionary.closeAll`

Dictionary Section Management

Data dictionaries store data as entries contained in sections, and by default all dictionaries have at least three sections named Design Data, Other Data, and Configurations. Use Simulink.data.dictionary.Section objects to interact with data dictionary sections.

Goal	Use
Represent data dictionary section with `Section` object.	`getSection` method
Interact with data dictionary section	`Simulink.data.dictionary.Section` class
Import variables to data dictionary section from MAT-file or MATLAB file	`importFromFile` method
Export entries in data dictionary section to MAT-file or MATLAB file	`exportToFile` method
Delete entry from data dictionary section	`deleteEntry` method
Evaluate MATLAB expression in data dictionary section	`evalin` method
Search for entries in data dictionary section	`find` method
Determine whether entry exists in data dictionary section	`exist` method

Dictionary Entry Manipulation

A variable that is stored in a data dictionary is called an entry of the dictionary. Entries have additional properties that store status information, such as the time and date the entry was last modified. Use Simulink.data.dictionary.Entry objects to manipulate data dictionary entries.

Goal	Use
Represent data dictionary entry with `Entry` object	`getEntry` method
Add data dictionary entry to section and represent with `Entry` object	`addEntry` method
Manipulate data dictionary entry	`Simulink.data.dictionary.Entry` class
Assign new value to data dictionary entry	`setValue` method
Display changes made to data dictionary entry	`showChanges` method
Save changes made to data dictionary	`saveChanges` method
Discard changes made to data dictionary entry	`discardChanges` method
Search in an array of data dictionary entries	`find` method
Return value of data dictionary entry	`getValue` method
Delete data dictionary entry	`deleteEntry` method
Store enumerated type definition in dictionary	`Simulink.data.dictionary.EnumTypeDefinition` class

Transition to Using Data Dictionary

Using a data dictionary can complicate programmatic interaction with model data. If you link a model to a dictionary:

You can no longer interact with the model data by using simple commands at the command prompt. Instead, you must use the programmatic interface of the dictionary (Simulink.data.Dictionary).
When you select the dictionary property Enable dictionary access to base workspace (see Continue to Use Shared Data in the Base Workspace), depending on the storage location of the target data, you must use either simple commands or the programmatic interface.

To help transition from using the base workspace to using data dictionaries, consider using these functions. The functions operate on model data regardless of the storage location of the data.

Goal	Use
Change value of data dictionary entry or workspace variable in context of Simulink model	`Simulink.data.assigninGlobal`
Evaluate MATLAB expression in context of Simulink model	`Simulink.data.evalinGlobal`
Determine existence of data dictionary entry or workspace variable in context of Simulink model	`Simulink.data.existsInGlobal`

Programmatically Migrate Single Model to Use Dictionary

To change the data source of a Simulink model from the MATLAB base workspace to a new data dictionary, use this example code as a template.

% Define the model name and the data dictionary name
modelName = 'f14';
dictionaryName = 'myNewDictionary.sldd';

% Load the target model
load_system(modelName);

% Identify all model variables that are defined in the base workspace
varsToImport = Simulink.findVars(modelName,'SourceType','base workspace');
varNames = {varsToImport.Name};

% Create the data dictionary
dictionaryObj = Simulink.data.dictionary.create(dictionaryName);

% Import to the dictionary the model variables defined in the base
% workspace, and clear the variables from the base workspace
[importSuccess,importFailure] = importFromBaseWorkspace(dictionaryObj,...
    'varList',varNames,'clearWorkspaceVars',true);

% Link the dictionary to the model
set_param(modelName,'DataDictionary',dictionaryName);

Note

This code does not migrate the definitions of enumerated data types that were used to define model variables. If you import model variables of enumerated data types to a data dictionary but do not migrate the enumerated type definitions, the dictionary is less portable and might not function properly if used by someone else. To migrate enumerated data type definitions to a data dictionary, see Enumerations in Data Dictionary.

Import Directly From External File to Dictionary

This example shows how to use a custom MATLAB function to import data directly from an external file to a data dictionary without creating or altering variables in the base workspace.

Create a two-dimensional lookup table in one sheet of a Microsoft^® Excel^® workbook. Use the upper-left corner of the sheet to provide names for the two breakpoints and for the table. Use column B and row 2 to store the two breakpoints, and use the rest of the sheet to store the table. For example, your lookup table might look like this:

Save the workbook in your current folder as my2DLUT.xlsx.

Copy this custom function definition into a MATLAB file, and save the file in your current folder as importLUTToDD.m.

function importLUTToDD(workbookFile,dictionaryName)
    % IMPORTLUTTODD(workbookFile,dictionaryName) imports data for a
    % two-dimensional lookup table from a workbook directly into a data
    % dictionary. The two-dimensional lookup table in the workbook can be
    % any size but must follow a standard format.

    % Read in the entire first sheet of the workbook.
    [data,names,~] = xlsread(workbookFile,1,'');

    % Divide the raw imported data into the breakpoints, the table, and their
    % names.
    % Assume breakpoint 1 is in the first column and breakpoint 2 is in the
    % first row.
    % Assume cells A2, B1, and B2 define the breakpoint names and table name.
    bkpt1 = data(2:end,1);
    bkpt2 = data(1,2:end);
    table = data(2:end,2:end);
    bkpt1Name = names{2,1};
    bkpt2Name = names{1,2};
    tableName = names{2,2};

    % Prepare to import to the Design Data section of the target data
    % dictionary.
    myDictionaryObj = Simulink.data.dictionary.open(dictionaryName);
    dDataSectObj = getSection(myDictionaryObj,'Design Data');

    % Create entries in the dictionary to store the imported breakpoints and
    % table. Name the entries using the breakpoint and table names imported
    % from the workbook.
    addEntry(dDataSectObj,bkpt1Name,bkpt1);
    addEntry(dDataSectObj,bkpt2Name,bkpt2);
    addEntry(dDataSectObj,tableName,table);

    % Save changes to the dictionary and close it.
    saveChanges(myDictionaryObj)
    close(myDictionaryObj)

At the MATLAB command prompt, create a data dictionary to store the lookup table data.
```
myDictionaryObj = Simulink.data.dictionary.create('myLUTDD.sldd');
```
Call the custom function to import your lookup table to the new data dictionary.
```
importLUTToDD('my2DLUT.xlsx','myLUTDD.sldd')
```
Open the data dictionary in Model Explorer.
```
show(myDictionaryObj)
```
Three new entries store the imported breakpoints and lookup table. These entries are ready to use in a 2-D Lookup Table block.

Programmatically Partition Data Dictionary

To partition a data dictionary into reference dictionaries, use this example code as a template. You can use reference dictionaries to make large data dictionaries more manageable and to contain standardized data that is useful for multiple models.

% Define the names of a parent data dictionary and two
% reference data dictionaries
parentDDName = 'myParentDictionary.sldd';
typesDDName = 'myTypesDictionary.sldd';
paramsDDName = 'myParamsDictionary.sldd';

% Create the parent data dictionary and a
% Simulink.data.Dictionary object to represent it
parentDD = Simulink.data.dictionary.create(parentDDName);

% Create a Simulink.data.dictionary.Section object to represent 
% the Design Data section of the parent dictionary
designData_parentDD = getSection(parentDD,'Design Data');

% Import some data to the parent dictionary from the file partDD_Data_ex_API.m
importFromFile(designData_parentDD,'partDD_Data_ex_API.m');

% Create two reference dictionaries
Simulink.data.dictionary.create(typesDDName);
Simulink.data.dictionary.create(paramsDDName);

% Create a reference dictionary hierarchy by adding reference dictionaries 
% to the parent dictionary
addDataSource(parentDD,typesDDName);
addDataSource(parentDD,paramsDDName);

% Migrate all Simulink.Parameter objects from the parent data dictionary to
% a reference dictionary
paramEntries = find(designData_parentDD,'-value','-class','Simulink.Parameter');
for i = 1:length(paramEntries)
    paramEntries(i).DataSource = 'myParamsDictionary.sldd';
end

% Migrate all Simulink.NumericType objects from the parent data dictionary
% to a reference dictionary
typeEntries = find(designData_parentDD,'-value','-class','Simulink.NumericType');
for i = 1:length(typeEntries)
    typeEntries(i).DataSource = 'myTypesDictionary.sldd';
end

% Save all changes to the parent data dictionary
saveChanges(parentDD)

Make Changes to Configuration Set Stored in Dictionary

You can store a configuration set (a Simulink.ConfigSet object) in the Configurations section of a dictionary. To change the setting of a configuration parameter in the set programmatically:

Create a Simulink.data.dictionary.Entry object that represents the configuration set (which is an entry in the dictionary). For example, suppose the name of the dictionary is myData.sldd and the name of the Simulink.ConfigSet object is myConfigs.
```
dictionaryObj = Simulink.data.dictionary.open('myData.sldd');
configsSectObj = getSection(dictionaryObj,'Configurations');
entryObj = getEntry(configsSectObj,'myConfigs');
```
Store a copy of the target Simulink.ConfigSet object in a temporary variable.
```
temp = getValue(entryObj);
```
In the temporary variable, modify the target configuration parameter (in this case, set Stop time to 20).
```
set_param(temp,'StopTime','20');
```
Use the temporary variable to overwrite the configuration set in the dictionary.
```
setValue(entryObj,temp);
```
Save changes made to the dictionary.
```
saveChanges(dictionaryObj)
```

Documentation