importFromFile

Import variables from MAT-file or MATLAB file to data dictionary section

Syntax

importedVars = importFromFile(sectionObj,fileName)

importedVars = importFromFile(sectionObj,fileName,'existingVarsAction',existAction)

[importedVars,existingVars] = importFromFile(___)

Description

importedVars = importFromFile(sectionObj,fileName) imports variables defined in the MAT-file or MATLAB file fileName to the data dictionary section sectionObj without overwriting any variables that are already in the target section. If any variables are already in the target section, the function displays a warning and a list in the MATLAB Command Window. This syntax returns a list of variables that were successfully imported. A variable is considered successfully imported only if importFromFile assigns the value of the variable to the corresponding entry in the target data dictionary.

importedVars = importFromFile(sectionObj,fileName,'existingVarsAction',existAction) imports variables that are already in the target section by taking a specified action existAction. For example, you can choose to use the variable values in the target file to overwrite the corresponding values in the target section.

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

Examples

Import to Data Dictionary from File

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

Import all variables contained in the file myData_ex_API.m to the data dictionary and return a list of successfully imported variables. If any variables are already in myDictionary_ex_API.sldd, importFromFile returns a warning and a list of the affected variables.

importFromFile(dDataSectObj,'myData_ex_API.m')

Warning: The following variables were not imported because
they already exist in the dictionary:
   fuelFlow 

ans = 

    'myFirstEntry'
    'mySecondEntry'
    'myThirdEntry'

Import Variables from File and Overwrite Conflicts

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

Import all variables contained in the file myData_ex_API.m to the data dictionary, overwrite any variables that are already in the dictionary, and return a list of successfully imported variables.

importFromFile(dDataSectObj,'myData_ex_API.m','existingVarsAction','overwrite')

ans = 

    'fuelFlow'
    'myFirstEntry'
    'mySecondEntry'
    'myThirdEntry'

Return Variables Not Imported to Data Dictionary from File

Return a list of variables that are not imported from a file because they are already in the target 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');

Import all variables contained in the file myData_ex_API.m to the data dictionary. Specify names for the output arguments of importFromFile to return the names of successfully and unsuccessfully imported variables.

[importedVars,existingVars] = importFromFile(dDataSectObj,'myData_ex_API.m')

importedVars = 

    'myFirstEntry'
    'mySecondEntry'
    'myThirdEntry'


existingVars = 

    'fuelFlow'

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

Input Arguments

sectionObj — Target data dictionary section

Simulink.data.dictionary.Section object

Target data dictionary section, specified as a Simulink.data.dictionary.Section object. Before you use this function, represent the target section with a Simulink.data.dictionary.Section object by using, for example, the getSection function.

fileName — Name of MAT or MATLAB file

character vector

Name of target MAT or MATLAB file, specified as a character vector. importFromFile automatically supplies a file extension .mat if you do not specify an extension.

Example: 'myFile.mat'

Example: 'myFile.m'

Data Types: char

existAction — Action to take for existing dictionary variables

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

Action to take for existing dictionary variables, specified as 'none', 'overwrite', or 'error'.

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

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

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

Example: 'overwrite'

Data Types: char

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 importFromFile assigns its value to the corresponding entry in the target data dictionary.

existingVars — 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 existAction is set to 'none', which is also the default. In that case importFromFile imports only variables that are not already in the target data dictionary.

Tips

• importFromFile 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

You can use the Model Explorer to import variables to a data dictionary from a file. See Import Data to Dictionary from File for more information.

Version History

Introduced in R2015a