COM2002X (ARCNET) Protocol I2C Protocol navigation bar

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 function. To write to the file, use the stream_send functions. To read from the file, use the stream_receive functions.

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 function, 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 function 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 function 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 function.

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 function 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 function 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 function 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

Warning

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

Warning

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

Warning

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

QUARC Win32 Target

Yes

Fully supported.

QUARC Win64 Target

Yes

Fully supported.

QUARC Linux Nvidia Target

Yes

Fully supported.

QUARC Linux QBot Platform Target

Yes

Fully supported.

QUARC Linux QCar 2 Target

Yes

Fully supported.

QUARC Linux QDrone 2 Target

Yes

Fully supported.

QUARC Linux Raspberry Pi 3 Target

Yes

Fully supported.

QUARC Linux Raspberry Pi 4 Target

Yes

Fully supported.

QUARC Linux RT ARMv7 Target

Yes

Fully supported.

QUARC Linux x64 Target

Yes

Fully supported.

QUARC Linux DuoVero Target

Yes

Fully supported.

QUARC Linux DuoVero 2016 Target

Yes

Fully supported.

QUARC Linux Verdex Target

Yes

Fully supported.

QUARC QNX x86 Target

Yes

Last fully supported in QUARC 2018.

See Also

 

navigation bar