importFromBaseWorkspace

Import base workspace variables to data dictionary

Syntax

importedVars = importFromBaseWorkspace(dictionaryObj)

importedVars = importFromBaseWorkspace(dictionaryObj,Name,Value)

[importedVars,existingVars] = importFromBaseWorkspace(___)

[importedVars,existingVars,unsupportedVars] = 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.

[importedVars,existingVars,unsupportedVars] = importFromBaseWorkspace(___) additionally returns a list of unsupported variables that were not imported. When there are unsupported variables in the base workspace, if you call this function without the unsupportedVars output argument, Simulink^® reports a warning.

Examples

Import All Base Workspace Variables to Data Dictionary

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 

Specify Variables to Import to Data Dictionary from Base Workspace

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'});

Import Variables from Base Workspace and Overwrite Conflicts

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 Variables Not Imported to Data Dictionary from Base Workspace

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.

Input Arguments

dictionaryObj — Target data dictionary

Simulink.data.Dictionary object

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 Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'varList',{'fuelFlow'}, 'existingVarsAction','overwrite' imports the variable fuelFlow and overwrites the corresponding entry in the data dictionary.

clearWorkspaceVars — Flag to clear base workspace of imported variables

false (default) | true

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

existingVarsAction — Action to take for existing dictionary variables

'none' (default) | 'error' | 'overwrite'

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

varList — Variables to import

cell array of character vectors | string array

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

importedVars — Successfully imported variables

cell array of character vectors

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.

existingVars — Existing variables that were not imported

cell array of character vectors

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.

unsupportedVars — Unsupported variables that were not imported

cell array of character vectors

Names of unsupported target variables that were not imported, returned as a cell array of character vectors. If this output argument is not included in the function call when there are unsupported variables, Simulink reports a warning. For the types of variables that can be imported into a data dictionary, see Valid Design Data Classes.

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.

• If the value of a variable is a timeseries object (which a data dictionary cannot store) or a structure with fields identical to a timeseries object, importFromBaseWorkspace cannot import the variable.

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.

Version History

Introduced in R2015a