To Host File

Writes the time and input, or video to a specified file on the host machine.

Library

Description

The To Host File block can be used to save inputs' time and data in various data file formats, or to save the input as a video file.

The To Host File block is available in the External Mode Control Panel just like a Scope. As such, it responds to the same triggering options as Scopes.

Data Files

The To Host File 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 To Host File 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 To Host File 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 To Host File 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 To Host File 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 To Host File 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.

Limitations

Network Access

On Windows Vista (and possibly higher versions of Windows), the To Host File 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 To Host File 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 To Host File 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 To Host File 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 To Host File 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 To Host File 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 To Host File 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 the QUARC Windows host (any QUARC target may be used however).

Input Ports

signal

For data files, the input for the To Host File block is the data that will be written to the MAT-file along with the simulation time.

For video files, the input for the To Host File 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 To Host File 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 To Host File block accepts all the data types that the Video Display block input accepts.

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 To Host File 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 To Host File 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 To Host File 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

See Also

• Host Disk
• File Write

Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.

Link to this page.