CL Stream Read End of trail navigation bar

Table of Contents

CL Stream Write

CL Stream Write

Owning Palette:Communications/Intermediate

Requirements:Quanser Rapid Control Prototyping Toolkit, LabVIEW 2020 or newer, Control Design and Simulation Module


Description

The CL 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 CL Stream Connect or CL Stream Accept VI is used to create the stream then the blocking mode of the stream is determined by the CL Stream Connect or CL Stream Listen VI.


Required Inputs All required inputs must be wired. They always appear as terminals on the VI palette. They also 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 CL Stream Write VI will be zero.


Optional Inputs or Dialog Box Options Optional inputs need not to be wired. They may appear as terminals or dialog parameters, but show up as dialog parameters by default. 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 CL 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 CL Stream Connect or CL Stream Accept VI is used to create the stream then the blocking mode of the stream is determined by the CL Stream Connect or CL 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 Optimize for 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 Send buffer size parameter of the CL Stream Call or CL 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 CL Stream Call or CL Stream Answer VIs.

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

Hint

Although it is intended for use in the main diagram with the other Intermediate stream VIs, the CL 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 bufsize 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 bufsize 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 bufsize 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


    See Also

  • CL Stream Read The CL Stream Read VI receives data over a stream.
  • CL Stream Answer

    The CL Stream Answer VI listens for and accepts a connection from a remote host using non-blocking I/O. Non-blocking I/O is used so that the I/O does not interfere with the sample rate of the VI. However, as a result, communication protocols that do not support non-blocking I/O are not supported by the Intermediate Stream VIs.

  • CL Stream CallThe CL Stream Call VI establishes a connection to a remote host using non-blocking I/O.

    Targets

    Target

    Supported

    Comments

    RCP Windows (64-bit) Target

    Yes

    Fully supported.

     

    navigation bar