Table of Contents > QUARC > User's Guide > QUARC Communications Protocols
File Protocol
The file protocol supports reading from and writing to a file on the local filesystem.
Syntax
file://hostname/path % Access a file on host 'hostname' at absolute path 'path' file:/path % Access a file on current machine at absolute path 'path' file:path % Access a file on current machine at relative path 'path'
Description
The file protocol supports reading from and writing to a file on the local filesystem. It is identified by using file as the protocol name in a URI.
The hostname and port in the URI are ignored, if specified. To specify an absolute path, either include the authority (hostname and optional port) followed by a "/" and the absolute path to the file, or omit the authority entirely and just specify the absolute path preceded by a "/". For example, the following URIs all specify the absolute path "/home/drmadill/myfile.dat".
file://localhost/home/drmadill/myfile.dat
file:/home/drmadill/myfile.dat
Likewise, the following URIs all specify the absolute path "C:\myfile.dat". Note that the drive letter may be followed by a ":" or by a "|". Forward slashes ("/") should always be used to separate folders in a path. The path will be converted internally to the appropriate operating-system specific format as required.
file://localhost/C:/Temp/myfile.dat
file:/C:/Temp/myfile.dat
To specify a path relative to the current directory omit the authority and leading "/". URIs that contain an authority (hostname and optional port) must use absolute paths for the file path because the "/" separates the authority component from the path. For example, the following URIs are relative paths:
file:../Temp/myfile.dat
file:myfile.dat
While the default access mode for files is read access, all file URIs should contain the mode option as specified below. Options appear after the "?" in the URI. For example,
file:myfile.dat?mode=w
Files are opened using the Stream Connect block. To write to the file, use the Stream Send block. To read from the file, use the Stream Receive block.
Note that it is only possible to write to the file if the mode option (see below) is specified as write-only, append, or read-write access. Similarly, it is only possible to read from the file if the mode option is specified as read-only, or read-write access. The default mode is read-only access. To avoid confusion it is always best to specify the mode.
Files are always accessed as binary files. Using text is accomplished by using the appropriate Stream blocks, not through the underlying file protocol. This technique ensures that text may be used with any protocol, not just files.
There are instances where it is convenient to know when a file has just been created or deleted. Listening streams, created using the Stream Listen block, are used for this purpose. When a listening stream is created for the file protocol it monitors the directory associated with the file for changes.
The Stream Accept block will return with a client stream representing the file specified in the URI when the listening stream detects that the file exists. Hence, the Stream Accept block can be used to wait for the file to be created (either directly or through renaming another file). It then opens the file with read-only access and outputs a handle to the file as the "client stream". Since the file is opened with read-only access it is only possible to read from the file returned by the Stream Accept block.
This mechanism is useful for designing a model that begins reading a file as soon as it is created. For example, the user may have an application that generates offline trajectory data that they want the model to read as soon as they have generated the trajectory. The best way to use this feature is to create the file in the same directory under a different name (from an application, for example) and then rename the file to the file name specified in the URI of the Stream Listen block once the data has been generated. The Stream Accept block associated with the listening stream will wake up as soon as the file is renamed and open the file for reading, outputting the file handle as the "client stream". A Stream Receive block may then be used with the returned stream to read the contents of the file. Note that the Stream Accept block opens the file immediately if it already exists at the time the Stream Accept block is executed.
It is also possible to detect when a file is deleted (or renamed). When used with a listening stream the Stream Poll block may be used for this purpose. Polling for the "Wait for a client connection to be ready to accept" (QCOMM_POLL_ACCEPT) condition causes the Stream Poll block to wait for the file to be created (either directly or through renaming another file). Polling for the "Wait for space available to send" (QCOMM_POLL_SEND) condition causes the Stream Poll block to wait for the file to be deleted (either directly or through renaming the file). This functionality allows a model to be designed in which a file is read every time it is created (if the application producing it renames or deletes the file each time it recreates it).
Limitations
Performance
The performance of the file protocol depends on the performance of the underlying file system. Clearly a floppy disk is going to be slower than a hard drive. |
Sharing
The file protocol supports different sharing modes. Whether more than one process can read or write to the file at the same time depends on the sharing mode. |
Listening
Not all operating systems support file system notification. Thus, the file protocol may not support the Stream Listen and Stream Accept blocks on those operating systems. Currently only the QUARC Target for Windows supports these two blocks with the file protocol. |
Options
mode
Sets the access mode used when opening the file. Valid access modes are:
Mode |
Description |
---|---|
r |
opens for reading. If the file does not exist or cannot be found, an error is returned. (default) |
r+ |
opens for both reading and writing. If the file does not exist or cannot be found, an error is returned. |
w |
opens for writing. If the file does not exist, it is created. If the file does exist, its contents are deleted. |
w+ |
opens for both reading and writing. If the file does not exist, it is created. If the file does exist, its contents are deleted. |
a |
opens for appending. If the file does not exist, it is created. If the file does exist, writes begin at the end of the file. The contents are not deleted. |
a+ |
opens for reading and appending. If the file does not exist, it is created. If the file does exist, writes begin at the end of the file. The contents are not deleted. |
share
Set this option to the desired sharing mode. The sharing mode determines whether more than one process can access the file at the same time as the model. Valid sharing modes are:
Mode |
Description |
---|---|
no |
Do not allow other processes to read from or write to the file. (default) |
r |
allows other processes to read from the file. |
w |
allows other processes to write to the file. |
rw |
allow other processes to read from or write to the file. |
If no share option is specified then sharing is not allowed.
Driver
The driver supporting the file protocol is called qrt_file
.
Targets
Target |
Supported |
Comments |
---|---|---|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Last fully supported in QUARC 2018. |
See Also
Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.
Link to this page.