Simulink.saveVars

Save workspace variables and their values in MATLAB code format

Syntax

Simulink.saveVars(filename)
Simulink.saveVars(filename, VarNames)
Simulink.saveVars(filename, '-regexp', RegExps)
Simulink.saveVars(filename, Specifications, UpdateOption)
Simulink.saveVars(filename, Specifications, Configuration)
Simulink.saveVars(filename, Specifications, MatlabVer)
[r1, r2] = Simulink.saveVars(filename, Specifications)


Note

Simulink.saveVars is not recommended. Use matlab.io.saveVariablesToScript instead.

Description

Simulink.saveVars(filename) saves all variables in the current workspace for which MATLAB^® code can be generated to a MATLAB file named filename.m. If MATLAB code cannot be generated for a variable, the variable is saved into a companion MAT-file named filename.mat, and a warning is generated. If either file already exists, it is overwritten. The filename cannot match the name of any variable in the current workspace, and can optionally include the suffix .m. Using Simulink.saveVars has no effect on the contents of any workspace.

Executing the MATLAB file restores the variables saved in the file to the current workspace. If a companion MAT-file exists, code in the MATLAB file loads the MAT-file, restoring its variables also. When both a MATLAB file and a MAT-file exist, do not load the MATLAB file unless the MAT file is available, or an error will occur. Do not load a MAT-file directly, or incomplete data restoration will result. No warning occurs if loading a file overwrites any existing variables.

You can edit a MATLAB file that Simulink.saveVars creates. You can insert comments between or within the MATLAB code sections for saved variables. However, if you later use Simulink.saveVars to update or append to the file, only comments between MATLAB code sections will be preserved. Internal comments should therefore be used only in files that you do not expect to change any further.

You must not edit the header section in the MATLAB file, which comprises the first five comment lines. Simulink^® does not check that a manually edited MATLAB file is syntactically correct. MathWorks recommends not editing any MATLAB code in the file. You cannot edit a MAT-file and should never attempt to do so.

Simulink.saveVars(filename, VarNames) saves only the variables specified in VarNames, which is a comma-separated list of variable names. You can use the wildcard character * to save all variables that match a pattern. The * matches one or more characters, including non-alphanumeric characters.

Simulink.saveVars(filename, '-regexp', RegExps) saves only variables whose names match one of the regular expressions in RegExps, which is a comma-separated list of expressions. See Regular Expressions for more information. A call to the function can specify both VarNames and -regexps RegExps, in that order and comma-separated.

Simulink.saveVars(filename, Specifications, UpdateOption) saves the variables described by Specifications (which represents the variable specifications in any of the above syntaxes) as directed by UpdateOption, which can be any one of the following:

• '-create' — Create a new MATLAB file (and MAT-file if needed) as directed by the Specifications. If either file already exists, it is overwritten. This is the default behavior.

• '-update' — Update the existing MATLAB file (and MAT-file if needed) specified by filename by changing only variables that match the Specifications and already exist in any files. The order of the variables in files is preserved. Comments within MATLAB code sections are not preserved.

• '-append' — Update the existing MATLAB file (and MAT-file if needed) specified by filename by:

  • Updating variables that match the Specifications and already exist in the file or files, preserving the existing order in the file or files. Comments within MATLAB code sections are not preserved.

  • Appending variables that match the Specifications and do not exist in the file or files by appending the variables to the file or files. These new sections initially have no comments.

Simulink.saveVars(filename, Specifications, Configuration) saves the variables described by Specifications (which represents the variable specifications in any of the above syntaxes) according to the specified Configuration. The Configuration can contain any or all of the following options, in any order, separated by commas if more than one appears:

• '-maxnumel' MaxNum — Limits the number of elements saved for an array to MaxNum, which must be an integer between 1 and 10000. For a character array, the upper limit is set to twice the value that you specify with MaxNum. If an array is larger than MaxNum, the whole array appears in the MAT-file rather than the MATLAB file, generating a warning. Default: 1000

• '-maxlevels' MaxLevels limits the number of levels of hierarchy saved for a structure or cell array to MaxLevels, which must be an integer between 1 and 200. If a structure or cell array is deeper than MaxLevels, the whole entity appears in the MAT-file rather than the MATLAB file, generating a warning. Default: 20

• '-textwidth' TextWidth sets the text wrap width in the MATLAB file to TextWidth, which must be an integer between 32 and 256. Default: 76

• '-2dslice' — Sets two dimensions for 2-D slices that represent n-D (where n is greater than 2) char, logic, or numeric array data. Simulink.saveVars uses the first two dimensions of the n-D array to specify the size of the 2-D slice, unless you supply two positive integer arguments after the -2dslice option. If you specify two integer arguments:

  • The two integers must be positive.

  • The two integers must be less than or equal to the number of dimensions of the n-D array.

  • The second integer must be greater than the first.

Simulink.saveVars(filename, Specifications, MatlabVer) acts as described by Specifications (which represents the specifications after filename in any of the above syntaxes) saving any MAT-file that it creates in the format required by the MATLAB version specified by MatlabVer. Possible values:

• '-v7.3' — 7.3 or later

• '-v7.0' — 7.0 or later

• '-v6' — Version 6 or later

• '-v4' — Any MATLAB version

[r1, r2] = Simulink.saveVars(filename, Specifications) acts as described by Specifications (which represents the specifications after filename in any of the above syntaxes) and reports what variables it has saved:

• r1 — A cell array of character vectors. The character vectors name all variables (if any) that were saved to a MATLAB file.

• r2 — A cell array of character vectors. The character vectors name all variables (if any) that were saved to a MAT-file.

Input Arguments

filename	The name of the file or names of the files that the function creates or updates. The filename cannot match the name of any variable in the current workspace. The filename can have the suffix .m, but the function ignores it.
VarNames	A variable or sequence of comma-separated variables. The function saves only the specified variables to the output file. You can use the wildcard character * to save all variables that match a pattern. The * matches one or more characters, including non-alphanumeric characters.
'-regexp', RegExps	After the keyword, a regular expression or sequence of comma-separated regular expressions. The function saves to the output file only those variables whose names match one of the expressions. See Regular Expressions for more information A call to the function can specify both VarNames and -regexps RegExps, in that order and comma-separated.
UpdateOption	Any of three keywords that control the action of the function. The possible values are: '-create' — Create a new MATLAB file (and MAT-file if needed) as directed by the Specifications. '-update' — Update the existing MATLAB file (and MAT-file if needed) specified by filename by changing only variables that match the Specifications and already exist in the file or files. The order of the variables in the file or files is preserved. '-append' — Update the existing MATLAB file (and MAT-file if needed) specified by filename by: Updating variables that match the Specifications and already exist in the file or files, preserving the existing order in the file or files. Appending variables that match the Specifications and do not exist in the file or files by appending the variables that match the Specifications to the file or files. Default: '-create'
Configuration	Any or all of the following options, in any order, separated by commas if more than one appears: '-maxnumel' MaxNum — Limits the number of elements saved for an array to MaxNum, which must be an integer between 0 and 10000. If an array is larger than that, the whole array appears in the MAT-file rather than the MATLAB script file, generating a warning. Default: 1000 '-maxlevels' MaxLevels — Limits the number of levels saved for a structure or cell array to MaxLevels, which must be an integer between 0 and 200. If a structure or cell array is deeper than that, the whole entity appears in the MAT-file rather than the MATLAB script file, generating a warning. Default: 20 '-textwidth' TextWidth — Sets the text wrap width in the MATLAB script file to TextWidth, which must be an integer between 32 and 256. Default: 76 '-2dslice' — Sets two dimensions for 2-D slices that represent n-D (where n is greater than 2) arrays of char, logic, or numeric data. Using the '-2dslice' option produces more readable generated code that is consistent with how MATLAB displays n-D array data. Simulink.saveVars uses the first two dimensions of the n-D array to specify the size of the 2-D slice, unless you supply two positive integer arguments after the -2dslice option. If you specify two integer arguments: The two integers must be positive. The two integers must be less than or equal to the number of dimensions of the n-D array. The second integer must be greater than the first. Note You can use the MATLAB Preferences to change the defaults for the -maxnumel, -maxlevels, '-2dslice', and -textwidth configuration options. In the Workspace pane, use the options in the Saving variables as MATLAB script files group.
MatlabVer	Specifies the MATLAB version whose syntax will be used by any MAT-file saved by the function. '-v7.3' — 7.3 or later '-v7.0' — 7.0 or later '-v6' — Version 6 or later '-v4' — Any MATLAB version Default: '-v7.3'

Output Arguments

r1	A list of the names of all variables (if any) that were saved to a MATLAB file.
r2	A list of the names of all variables (if any) that were saved to a MAT-file.

Examples

Define some base workspace variables, then save them all to a new MATLAB file named MyVars.m using the default values for all input arguments except the filename.

a = 1;
b = 2.5;
c = 'A string';
d = {a, b, c};
Simulink.saveVars('MyVars');

Define additional base workspace variables, then append them to the existing file MyVars.m without changing the values previously saved in the file:

K = Simulink.Parameter;
MyType = fixdt (1,16,3);
Simulink.saveVars('MyVars', '-append', 'K', 'MyType');

Update the variables V1 and V2 with their values in a MATLAB file, or for any whose value cannot be converted to MATLAB code, in a MAT-file. The file must already exist. Any array with more than 10 elements will be saved to a MAT-file that can be loaded on any version of MATLAB. The return argument r1 lists the names of any variables saved to a MATLAB file; r2 lists any saved to a MAT-file.

[r1, r2] = Simulink.saveVars('MyFile', 'V1', 'V2', '-update',
'-maxnumel', 10, '-v4');

Specify a 2-D slice for the output of the my3Dtable 3-D array. Specify that the 2-D slice expands along the first and third dimensions:

my3DTable = zeros(3, 4, 2, 'single');
Simulink.saveVars('mfile.m', 'my3DTable', '-2dslice', 1, 3);

The generated MATLAB code is:

my3DTable = zeros(3, 4, 2, 'single');
my3DTable (:,1,:) = single ( ...
  [1 13;
   5 17;
   9 21]);
my3DTable (:,2,:) = single( ...
  [2 14;
   6 18;
   10 22]);
my3DTable (:,3,:) = single( ...
  [3 15;
   7 19;
   11 23]);
my3DTable (:,4,:) = single( ...
  [4 16;
   8 20;
   12 24]);

Limitations

The Simulink.saveVars function:

• Does not preserve shared references.

• Ignores dynamic properties of objects.

• Saves the following to the MAT-file although they could appear in the MATLAB file:

  • Simulink.ConfigSet objects with custom target components.
    (Use the Simulink.ConfigSet method saveAs instead.)

  • Simulink.Timeseries and Simulink.ModelDataLogs objects.

If you save many variables, the generated MATLAB file can contain many lines of code and take a long time to execute. To avoid the long execution time, consider these alternatives:

• Permanently store variables in a data dictionary instead of using Simulink.saveVars. A data dictionary also provides more tools for managing variables. See Determine Where to Store Variables and Objects for Simulink Models.

• Save variables in a MAT-file by using the save function.

Tips

• If you do not need to save variables in an easily-understood form, see the save function.

• If you need to save only bus objects, use the Simulink.Bus.save function.

• If you need to save only a configuration set, use the Simulink.ConfigSet.saveAs method.