Stream Read End of trail navigation bar

Table of Contents

Stream Write

Stream Write

Owning Palette:Not available in this version of RCP Toolkit. Please check for updates.

Requirements:Quanser Rapid Control Prototyping Toolkit, LabVIEW 2020 or newer


Description

The Stream Write VI writes data to the stream buffer. The operation of this VI is affected by the blocking mode of the stream connected to its input. Streams have two modes: blocking (the default) and non-blocking. If a Stream Call or Stream Answer VI is used to create the stream, then the stream will be non-blocking. If a Stream Connect or Stream Accept VI is used to create the stream then the blocking mode of the stream is determined by the Stream Connect or Stream Listen VI.


Required Inputs All required inputs must be wired. They appear in bold text in the context help window for the VI.
steam in

steam in is a reference to the stream created by the Stream Call or Stream Answer VI. If these VIs have not established a connection the err output of the Stream Write VI will be zero.


Optional Inputs Optional inputs need not to be wired. They are indicated but not labelled in the context help window for the VI.
optimize for

optimize for determines whether the VI is optimized for maximizing throughput or minimizing latency. If this option is set to maximize throughput, then the VI only flushes the stream buffer to the underlying communication channel when the stream buffer is full. In this way, as much data as possible can be transferred in each packet for packet-based protocols such as TCP/IP or UDP.

If this option is set to minimize latency then it flushes the stream buffer to the underlying communication channel each time the VI executes. Doing so minimizes the time between when the data is generated and when it is sent to the remote host, but it may under-utilize the communications bandwidth since packets may not be full when they are sent.


Outputs

steam out

steam out is a reference to the stream. This output is merely a copy of the stm input.

sent?

sent? is a Boolean value indicating whether the input signal was written to the stream buffer successfully. This value will be true (non-zero) if the data was written successfully and zero otherwise. If the data could not be written immediately without blocking then this output will be zero. This output merely indicates that the data was written to the stream buffer. It does not validate that the data was sent to the underlying communication channel or delivered to the remote peer successfully.

no designated peer?

no designated peer? is a Boolean value indicating whether an error has occurred due to the peer not yet being designated. For a UDP server, the client is generally unknown until the first receive operation has been completed successfully, because the UDP protocol is a connection-less protocol. Not knowing the peer means no data will be sent. However, it is not regarded as a fatal error because the stream does not need to be closed in this case. It merely indicates that no client has "connected" yet by sending a datagram to the server. The UDP server should continue listening on the port and attempting to receive data. This output can be used to determine why no data has been sent (see the sent? port) when there are no other errors and the operation should not have blocked.

error out error out contains error information. If the error in cluster indicated an error, the error out cluster contains the same information. Otherwise, error out describes the error status of this VI.
status icon status is TRUE if an error occurred. If status is TRUE, the VI does not perform any operations.
code icon code is the error code number identifying an error. A value of 0 means no error, a negative value means a fatal error, and a positive value is a warning. Refer to the Quanser Error Codes for a code description.
source icon source identifies where an error occurred. The source string is usually the name of the VI that produced the error.


Details

The Stream Write VI writes data to the stream buffer. The operation of this VI is affected by the blocking mode of the stream connected to its input. Streams have two modes: blocking (the default) and non-blocking. If a CL Stream Call or CL Stream Answer VI is used to create the stream, then the stream will be non-blocking. If a Stream Connect or Stream Accept VI is used to create the stream then the blocking mode of the stream is determined by the Stream Connect or Stream Listen VI.

This VI attempts to store all of the data at its data input in the stream buffer. If the stream has been configured to swap bytes due to endian differences then this VI will swap the order of the bytes within each element in the input signal when storing the data in the stream buffer. If the parameter is set to minimize latency then it will also flush the stream each time that it executes. Otherwise, it only flushes the stream buffer to the underlying communication channel when the stream buffer is full. The size of the stream buffer is set by the parameter of the Stream Call or Stream Answer VI that created the stream.

If an error occurs, it will be reported to Control and Simulation Loop. If the connection is closed it is considered an error condition. If the stream is not valid because it is not yet connected, the VI will not report error since this condition is expected and the validity of the stream may be checked using the state output of the Stream Call or Stream Answer VIs.

This VI does not support two threads calling Stream Write at the same time. However, Stream Write may be called by another thread at the same time as Stream Read.

Hint

Although it is intended for use in the main diagram with the other Intermediate stream VIs, the Stream Write VI may be used with the Advanced stream VIs, even in an asynchronous thread.

Hint

For packet or message-based protocols in non-blocking mode, the number of bytes sent over the communication channel in each packet may be larger than the number of bytes in the input signal, even if the VI is configured to minimize latency. If the data cannot be flushed to the underlying communication channel without blocking then it remains in the stream buffer and will be written to the underlying communication channel along with the new data on the next sampling instant. This situation is typically recognized when a QERR_DATAGRAM_TOO_LARGE error is returned at the peer when trying to receive the data.

Hint

The number of bytes in each packet may be as large as the stream buffer size unless the underlying protocol restricts the maximum packet size. For example, the option of the UDP protocol has a default value of 1492 bytes. Hence, up to 1492/8 = 186 doubles may appear in a single datagram at the peer if the stream buffer is more than 1492 bytes in size. To restrict the size of the datagrams sent, either reduce the stream buffer size or set the option of the UDP URI. Reducing the stream buffer size may cause new data to be discarded if there is not enough room in the stream buffer, but it limits the number of datagrams sent. Setting the option of the UDP URI causes the stream API to send multiple datagrams, if necessary, to flush the stream buffer. A typical URI would be "udp://localhost:18000?bufsize=512", which sets the maximum datagram size to 512 bytes (64 doubles).

Hint

An even better solution is to allow the datagrams to be large and instead receive the full datagram at the peer. For example, if the stream buffer size and maximum datagram size are both 1492 bytes, then attempt to receive 1492 bytes at the peer (or 187 doubles).


Feedthrough Behaviour

All input/output pairs of this function have direct feedthrough behaviour.


Examples

  • RCP CL Comm Advanced Stream Example
  • RCP CL Comm Intermediate Stream Example
  • RCP CL Comm Intermediate Stream Mixed Type Example

    Targets

    Target

    Supported

    Comments

    RCP Windows (64-bit) Target

    Yes

    Fully supported.

     

    navigation bar