Table of Contents
File Write
Writes the time and input, or video to a specified file on the target machine.
Library
MATLAB Command Line
Click to copy the following command line to the clipboard. Then paste it in the MATLAB Command Window:
qc_open_library('quarc_library/Sinks/To Host')Description
The File Write block can be used to save inputs' time and data in various data file formats, or to save the input as a video file on the target machine.
Data Files
The File Write block writes its scalar or vector input to a matrix in a file. The block writes the data as well as the simulation time (except for certain formats). Its icon shows the name of the specified output file. Note that the File Write block does not accept matrix signals.
The block supports a variety of file formats. Supported file formats include MAT-files (version 4 or version 5), M-files, CSV files, text files and raw binary files. The file format is determined by the File format parameter.
For MAT-files and M-files, the block writes one column for each time step, where the first row contains the simulation time and the remaining rows contain the input data (scalar or vector) for each time sample. The matrix has the following form:
where the vector [u1, ..., un]
is the input data at a single sample time.
The File Write block generates uncompressed MAT-files. If the specified MAT-file exists at the time the simulation starts, the block overwrites its contents. If the maximum size supported by the MAT-file format would be exceeded then the block stops with an error. The data in the MAT-file will be valid despite the error.
For CSV files, the block writes one row for each time step, where the first column contains the simulation time and the remaining columns contain the input data (scalar or vector) for each time sample.
The text file format is special in that it requires a string to be supplied at the block's input port (a null-terminated vector of uint8's containing characters). The string is typically generated using the String Print block. In this case, the File Write block simply outputs the string to the file each sampling instant. The simulation time is not included in the file unless it is part of the string.
The raw binary file format is used to write pure binary data to a file. In this case, the File Write block simply writes the value of its input to the file as binary data. The simulation time is not included in the binary data. If the simulation time is desired, simply include it in the input to the block. To read the binary data into MATLAB, execute commands such as the following:
fid = fopen('data.bin', 'rb'); % assuming 'data.bin' is the name of the data file data = fread(fid, [n, inf], 'double'); % where n is the number of elements in the input vector fclose(fid);
Note, however, that reading raw binary files can take much longer than loading a MAT file. The raw binary file format is intended more for external applications to read, such as a C program.
Video Files
The File Write block accepts any input data types or formats that the Video Display block accepts, and save the images stream as either MP4 or WMV files. If the specified video file exists at the time the simulation starts, the block overwites its contents. Unlike the To Host File block, the File Write block does not accept the output of a Channel block at its input.
Limitations
Network Access
On Windows Vista (and possibly higher versions of Windows), the File Write block may not be able to write to a mapped network drive immediately after a reboot. Only after the network drive is accessed in Windows Explorer will it be able to access the file. The problem is due to a known issue in Windows Vista when User Account Control (UAC) is enabled that arises because network shares that are mapped are shared with the standard user access token instead of with the full administrator access token. Refer to Enabling Linked Connections to correct the problem.
MAT-file v.4 Fornmat
The MAT-file v.4 file format limits the size of matrices to 100 million elements. Since time is stored in addition to the input signal values by the File Write block, the number of rows of the data will be one more than the number of elements in the input vector. There is one column stored for each sampling instant (assuming no decimation), so the total number of samples that can be stored will be 100 million divided by the number of rows. Use the MAT-file v.5 format to store larger matrices.
If the limit is reached, the block stops with an error but the MAT-file will still be valid.
MAT-file v.5 Fornmat
The MAT-file v.5 file format limits the size of matrices to approximately 536870898 elements (536 million). Since time is stored in addition to the input signal values by the File Write block, the number of rows of the data will be one more than the number of elements in the input vector. There is one column stored for each sampling instant (assuming no decimation), so the total number of samples that can be stored will be 536870898 divided by the number of rows. Use the raw binary file format to store larger matrices.
If the limit is reached, the block stops with an error but the MAT-file will still be valid.
Helpful Hints
Filename Substitutions
The filename specified in the File Write block may contain any of the format specifiers supported
by the qc_perform_substitutions command. The most useful of these specifiers
is probably the %{date}
, %{time}
and %{instance}
expressions, which allow the
date, time or an instance counter to be used as part of the filename. For example, a filename of
data_%{time}.mat
will produce a new file every time you run the model, with the time the
model was run appended to the name of the file. See the filename parameter
for other format specifiers.
Variable Name Substitutions
The variable name specified in the File Write block may also contain any of the format specifiers supported by the qc_perform_substitutions command. This feature is useful for creating variable names that include the current time or an instance number so that multiple data files may be loaded without variable name conflicts.
Directory Creation
If the Filename parameter contains a directory path as part of the filename then the File Write block will create any components of the path that do not exist. This feature is particularly useful with the %{date} format specifier because it allows data files to automatically be saved in a subdirectory based on the current date. For example, entering a filename of "%{date}/data_%{time}.mat" will create a subdirectory whose name is the current date, and creates a data file in that directory whose name includes the current time.
UNC Filenames
The File Write block supports UNC filenames, which allows the MAT-file to be saved to another computer on the local area network. For example, the filename "\\myfriend\SharedDocs\mydata.mat" would save the MAT-file "mydata.mat" in the SharedDocs folder of the computer called "myfriend". UNC filenames only work on Windows platforms.
Input Ports
signal
For data files, the input for the File Write block is the data that will be written to the MAT-file along with the simulation time.
For video files, the input for the File Write block are the images that will be written to the video file. Images compressed with the Image Compress block are supported.
header
This optional input supplies the text for the header to write to the beginning of the file. It is only present if
the Formatting options parameter is Include header and footer or
Include header only. It must be a string represented as a null-terminated vector of ANSI
(uint8
) characters. A String Constant or
String Print block is typically used to supply the string.
footer
This optional input supplies the text for the footer to write to the end of the file. It is only present if
the Formatting options parameter is Include header and footer or
Include footer only. It must be a string represented as a null-terminated vector of ANSI
(uint8
) characters. A String Constant or
String Print block is typically used to supply the string.
filename
A string specifying the filename of the file to which to write. The string
must be a null-terminated vector of characters represented as a vector of uint8
quantities.
It may be variable-sized. This string is typically provided either directly or indirectly by a
Model Argument
block or String Constant block.
This input is only available if the Source of filename parameter is
set to External input port
. Refer to the documentation below on the
Source of filename parameter for details.
Output Ports
This block has no output ports.
Data Type Support
Data Files
The File Write block accepts signals of any of the built-in Simulink data types. Fixed point is not supported. Note that although the block accepts input signals of any of the built-in Simulink data types, for most format types, all data is saved as double-precision data. The exception is the text and raw binary file formats. The text file format stores data as characters while the binary file format stores data as the same type as the input signal. The text and raw binary file formats also support variable-size signals, while the other formats do not.
Complex signals are supported. In the binary format, the real and imaginary parts are interleaved i.e., real, imag, real, imag, ...
Video Files
The File Write block accepts all the data types that the Video Display block input accepts. However, it does not accept the output of a Channel block.
Parameters and Dialog Box
Source of filename
Indicates whether the filename should be determined from the dialog parameters or an
input port. If this field is set to Specify via dialog (do not evaluate)
then
the filename is specified via the Filename
parameter. In this case, the filename is not evaluated as a MATLAB expression but is
interpreted as a literal string. However, format specifiers are recognized. Refer
to qc_perform_substitutions
for a list of the format specifiers available.
If format specifiers which change frequently, such as '%{time}' or
'%{instance}', are used in the filename then the File Write block cannot be placed
in a referenced model, because the filename will change from the time the code is built to when
the code is run. As a result, Simulink will insist that the code be rebuilt because block
parameters in referenced models are inlined. Instead, specify the source of the filename as
External input port
and pass the filename from the top-level model. Use a
String Constant block
in the top-level model to generate the filename.
If this field is set to Specify via dialog (evaluate)
then the filename is also specified
via the Filename parameter. However, in this case,
the filename is evaluated as a MATLAB expression. This option is convenient for using a variable
in the MATLAB workspace for the filename.
If this field is set to External input port
then the Filename
parameter is ignored and an extra input port is provided which determines the filename.
Filename (tunable offline)
Data Files
The name of the data file where the input data should be written. If no file extension is provided then the block automatically adds a file extension appropriate to the selected file format. To force no file extension to be used simply put a '.' at the end of the filename.
Video Files
The name of the video file where the input image should be written. If no file extension is provided then the File Write block automatically adds a file extension of .mp4, which means the resulting video is encoded using H.264 compression standard. The other supported compression standard is Windows Media Video 9, with a corresponding extension of .wmv.
All Files
This field is only used if the Source of filename parameter is set to Specify via dialog (do not evaluate)
or Specify via dialog (evaluate)
.
If the Source of filename parameter is set to Specify via dialog (do not evaluate)
then the
filename may contain format specifiers. This capability can be useful for automatically generating new file names that
include the date or time, for example. For a full list of specifiers see the
qc_perform_substitutions function.
Variable name (tunable offline)
This parameter is only enabled for Data Files.
The name of the array variable saved in the MAT-file that will contain the time and input data.
The variable name may contain format specifiers. This capability can be useful for automatically generating new file names that include the time or an instance number, for example. For a full list of specifiers see the qc_perform_substitutions function.
Decimation (tunable offline)
This parameter is only enabled for Data Files.
This parameter allows the block to write data at every nth sample, where n is the decimation factor. The default decimation is 1, which writes data at every time step.
Sample time
The sample time of the block. A sample time of 0 indicates that the block will be treated as a continuous time block. A positive sample time indicates that the block is a discrete time block with the given sample time.
A sample time of -1 indicates that the block inherits its sample time from the input. The block inherits the sample time by default.
To set the sample time to the fundamental sampling time of the model, use the qc_get_step_size function, which is a QUARC function that returns the fundamental sampling time of the model. The fundamental sampling time of the model is the sampling time entered in the Fixed step size field of the Solver pane of the Configuration parameters.
File format (tunable offline)
Allows the file format to be selected. Valid file formats are MAT-file v.4, MAT-file v.5, M-file, CSV file, text file, raw binary file and video file. MAT-file v.4 is the default format. Note that if the MAT-file is opened in MATLAB and then saved again it will be stored in the format compatible with the user's MATLAB version.
Formatting options
Adds extra optional input ports to add a header and/or footer to the file. The inputs are evaluated and written to the output in the first sampling instant in which the File Write block executes. This option is only used when the file format is M-file, CSV-file or Text file. The other file formats do not allow a header or footer to be added. A String Constant or String Print block is typically used to supply the header or footer strings.
Append to file
Check this option to append to the file instead of overwriting the file. This option is only used when the file format is M-file, CSV-file, Text file or Raw binary file. The other file formats always overwrite the file.
Bitrate
This parameter is only used when file format is Video file. Specify the suggested bitrate for the video. Refer to YouTube recommended upload encoding settings for recommended bitrates for different intended video usages.
Targets
Target Name |
Compatible* |
Model Referencing |
Comments |
---|---|---|---|
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
Last fully supported in QUARC 2018. |
|
Rapid Simulation (RSIM) Target |
Yes |
Yes |
|
S-Function Target |
No |
N/A |
Old technology. Use model referencing instead. |
Normal simulation |
Yes |
Yes |
See Also
Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.
Link to this page.