importFromBaseWorkspace

Class: Simulink.data.Dictionary
Package: Simulink.data

Import base workspace variables to data dictionary

Syntax

importedVars = importFromBaseWorkspace(dictionaryObj)
importedVars = importFromBaseWorkspace(dictionaryObj,Name,Value)
[importedVars,existingVars] = importFromBaseWorkspace(___)

Description

importedVars = importFromBaseWorkspace(dictionaryObj) imports all variables from the MATLAB base workspace to the data dictionary dictionaryObj without overwriting existing entries in the dictionary. If any base workspace variables are already in the dictionary, the function present a warning and a list.

This syntax returns a list of names of the successfully imported variables. A variable is considered successfully imported only if importFromBaseWorkspace assigns the value of the variable to the corresponding entry in the target data dictionary.

importedVars = importFromBaseWorkspace(dictionaryObj,Name,Value) imports base workspace variables to a data dictionary, with additional options specified by one or more Name,Value pair arguments.

[importedVars,existingVars] = importFromBaseWorkspace(___) additionally returns a list of variables that were not overwritten. Use this syntax if existingVarsAction is set to 'none', the default value, which prevents existing dictionary entries from being overwritten.

Input Arguments

expand all

Target data dictionary, specified as a Simulink.data.Dictionary object. Before you use this function, represent the target dictionary with a Simulink.data.Dictionary object by using, for example, the Simulink.data.dictionary.create or Simulink.data.dictionary.open function.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Flag to clear the base workspace of any successfully imported variables, specified as the comma-separated pair consisting of 'clearWorkspaceVars' and true or false.

Example: 'clearWorkspaceVars',true

Data Types: logical

Action to take for existing dictionary variables, specified as the comma-separated pair consisting of 'existingVarsAction' and 'none', 'error', or 'overwrite'.

If you specify 'none', importFromBaseWorkspace attempts to import target variables but does not import or make any changes to variables that are already in the data dictionary.

If you specify 'error', importFromBaseWorkspace returns an error, without importing any variables, if any target variables are already in the data dictionary.

If you specify 'overwrite', importFromBaseWorkspace imports all target variables and overwrites any variables that are already in the data dictionary.

Example: 'existingVarsAction','error'

Data Types: char

Names of specific base workspace variables to import, specified as the comma-separated pair consisting of 'varList' and a cell array of character vectors or a string array. If you want to import only one variable, specify the name inside a cell array. If you do not specify 'varList', importFromBaseWorkspace imports all variables from the MATLAB base workspace.

Example: 'varList',{'a','myVariable','fuelFlow'}

Example: 'varList',{'fuelFlow'}

Data Types: cell

Output Arguments

expand all

Names of successfully imported variables, returned as a cell array of character vectors. A variable is considered successfully imported only if importFromBaseWorkspace assigns the value of the variable to the corresponding entry in the target data dictionary.

Names of target variables that were not imported due to their existence in the target data dictionary, returned as a cell array of character vectors. existingVars has content only if 'existingVarsAction' is set to 'none' which is also the default. In that case importFromBaseWorkspace imports only variables that are not already in the target data dictionary.

Examples

expand all

In the MATLAB base workspace, create variables to import.

a = 'Char Variable';
myVariable = true;
fuelFlow = 324;

Open the data dictionary myDictionary_ex_API.sldd and represent it with a Simulink.data.Dictionary object named myDictionaryObj.

myDictionaryObj = Simulink.data.dictionary.open('myDictionary_ex_API.sldd');

Import all base workspace variables to the data dictionary and return a list of successfully imported variables. If any base workspace variables are already in myDictionary_ex_API.sldd, importFromBaseWorkspace presents a warning and a list of the affected variables.

importFromBaseWorkspace(myDictionaryObj);
Warning: The following variables were not imported because 
they already exist in the dictionary:
   fuelFlow 

In the MATLAB base workspace, create variables to import.

b = 'Char Variable';
mySecondVariable = true;
airFlow = 324;

Open the data dictionary myDictionary_ex_API.sldd and represent it with a Simulink.data.Dictionary object named myDictionaryObj.

myDictionaryObj = Simulink.data.dictionary.open('myDictionary_ex_API.sldd');

Import only the new base workspace variables to the data dictionary.

importFromBaseWorkspace(myDictionaryObj,'varList',...
{'b','mySecondVariable','airFlow'});

In the MATLAB base workspace, create a variable to import.

fuelFlow = 324;

Open the data dictionary myDictionary_ex_API.sldd and represent it with a Simulink.data.Dictionary object named myDictionaryObj. myDictionary_ex_API.sldd already contains an entry called fuelFlow.

myDictionaryObj = Simulink.data.dictionary.open('myDictionary_ex_API.sldd');

Import the variable fuelFlow and overwrite the corresponding entry in myDictionary_ex_API.sldd.

importFromBaseWorkspace(myDictionaryObj,'varList',{'fuelFlow'},...
'existingVarsAction','overwrite');

importFromBaseWorkspace assigns the value of the base workspace variable fuelFlow to the value of the corresponding entry in myDictionary_ex_API.sldd.

Return a list of variables that are not imported from the MATLAB base workspace because they are already in the target data dictionary.

In the MATLAB base workspace, create variables to import.

fuelFlow = 324;
myNewVariable = 'This is a character vector.'

Open the data dictionary myDictionary_ex_API.sldd and represent it with a Simulink.data.Dictionary object named myDictionaryObj. myDictionary_ex_API.sldd already contains an entry called fuelFlow.

myDictionaryObj = Simulink.data.dictionary.open('myDictionary_ex_API.sldd');

Import the variables fuelFlow and myNewVariable to the data dictionary. Specify names for the output arguments of importFromBaseWorkspace to return the names of successfully and unsuccessfully imported variables.

[importedVars,existingVars] = importFromBaseWorkspace(myDictionaryObj,...
'varList',{'fuelFlow','myNewVariable'})
importedVars = 

    'myNewVariable'


existingVars = 

    'fuelFlow'

importFromBaseWorkspace does not import the variable fuelflow because it is already in the target data dictionary.

Tips

  • importFromBaseWorkspace can import MATLAB variables created from enumerated data types but cannot import the definitions of the enumerated types. Use the importEnumTypes function to import enumerated data type definitions to a data dictionary. If you import variables of enumerated data types to a data dictionary but do not import the enumerated type definitions, the dictionary is less portable and might not function properly if used by someone else.

Alternatives

  • When you use the Simulink Editor to link a model to a data dictionary, you can choose to import model variables from the base workspace. See Migrate Single Model to Use Dictionary for more information.

  • You can also use the Model Explorer window to drag-and-drop variables from the base workspace into a data dictionary.

Introduced in R2015a