CL Stream Read (I8 Scalar)

Parent Polymorphic VI: CL Stream Read

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

Description

The CL Stream Read VI receives data over a stream. 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.

stream in is a reference to the stream. This output is merely a copy of the stream in input.

Recommended Inputs or Dialog Box Options Recommended inputs need not to be wired. They may be selected to appear as terminals or dialog parameters, but show up as terminals by default. They appear in simple text in the context help window for the VI.

default is the value of the default output.

Outputs

	stream out is a reference to the stream. This output is merely a copy of the steam in input.
	data read from the stream buffer. The output signal is treated as an atomic unit. It will never read part of the data from the stream buffer. Note that the buffer size for the stream must be at least as large as the output data or `-QERR_STREAM_BUFFER_TOO_SMALL` is raised.
	new indicates whether the value(s) presented at the data port represent newly received data from the peer. If this output is zero (false) then no data has been received from the peer in this sampling instant.
	closed indicates whether the connection has been closed by the peer. This output is non-zero (true) when the remote host gracefully closes the connection. Otherwise it is zero (false).

Details

This VI receives values over a client stream, where the size and data type of the signal is determined by the default. If the stream has been configured to swap bytes then this VI will swap the order of the bytes within each element that it reads before writing them to its data output. Multi-dimensional and bus signals are supported.

Since the Intermediate Stream VIs are non-blocking, this VI does not wait. If fewer bytes are available than the size of the output signal then the new output will be zero (false). If all the data requested is available then the new output will be non-zero (true).

If the connection has been closed gracefully by the peer then it sets closed to a non-zero (true) value and returns zero (false) at its new output once there are fewer bytes left to read than the size of the output signal. Otherwise the closed output is zero and the new output returns true (non-zero). Once there are fewer bytes left in the stream buffer than the size of the output data vector then it sets closed to true to indicate the connection has been closed. A graceful closure of the connection by the peer is not considered an error.

If an error occurs, it will be reported to Control and Simulation Loop. If the stream is not valid because it is not yet connected, it will not be considered an err 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 Read at the same time. However, CL Stream Read may be called by another thread at the same time as CL Stream Write.

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

	CL Stream Write	The CL Stream Write VI writes data to the stream buffer.
	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 Call	The CL Stream Call VI establishes a connection to a remote host using non-blocking I/O.