navigation bar

Stream Answer

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

Recommended Inputs Recommended inputs need not be wired. They appear as simple text in the context help window for the VI.

listen close used to close the listening stream. Setting this input to a non-zero value will cause the VI to stop listening for connections from remote clients. The listening stream will remain closed as long as this input is non-zero. When this input is zero or `false`, then a new listening stream will be created and the VI will begin accepting connections from remote hosts. The VI will continue listening as long as this input is zero. This input is ignored if the VI is currently connected to a remote host. In general, this input should always be zero.

client close used to close the connection to the client. Setting this input to a non-zero value will cause the connection to be closed. The connection will remain closed as long as this input is non-zero. When this input is zero or `false`, then a new connection will be established. The connection will be maintained as long as this input is zero.

error in describes error conditions occurring before the VI executes. If an error has already occurred, the VI returns the value of the error in cluster in error out.

status is TRUE if an error occurred. If status is TRUE, the VI does not perform any operations.

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 identifies where an error occurred. The source string is usually the name of the VI that produced the error.

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

send buffer size used by the stream for sending data. This buffer is independent of any buffering in the underlying communication protocol. Increasing the buffer size may increase transmission performance. The buffer size must be at least as large as the maximum vector that will be sent. For example, if a double 3-vector is transmitted using the Stream Write VI then the stream buffer size must be at least 24 bytes in length since a double is 8 bytes and a 3-vector is being sent.

byte ordering in which bytes are transmitted or received. Little endian ordering means that the least significant byte of individual values, such as doubles, is transmitted or received first. Big endian ordering means that the most significant byte of individual values is transmitted or received first. The remote host must use the same byte ordering.

uri is a string specifying the URI upon which to listen for client connections.

receive buffer size used by the stream for receiving data. This buffer is independent of any buffering in the underlying communication protocol. Increasing the buffer size may increase reception performance. The buffer size must be at least as large as the maximum vector that will be received. For example, if a double 5-vector is received using the Stream Read VI then the stream buffer size must be at least 40 bytes in length since a double is 8 bytes and a 5-vector is being received.

Outputs

stream is a reference to the stream. This reference is always valid but will not refer to a connected stream if the connection was not established or is still pending. It has a data type of t_stream_ptr. It may only be connected to the stream in input of one of the Stream VIs. It may not be connected to a Stream Accept VI. Attempting to do so will result in an error being returned by the Stream Accept VI.

state is a uint8 state code indicating the current status of the connection. The different connection states and their values are given in the table below in the Details section.

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 is TRUE if an error occurred. If status is TRUE, the VI does not perform any operations.
	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 identifies where an error occurred. The source string is usually the name of the VI that produced the error.

Details

The first time the VI executes it creates a listening stream. The next time it executes it attempts to accept a connection from a remote host. It does not wait for remote hosts to connect, but attempts to accept a connection each time the VI executes. Once a connection is established, it outputs the connection at its stm port. This stream signal is passed as an input to other Intermediate Stream VIs to refer to the stream.

The connection is maintained as long as the client close input remains zero or false. If the client close becomes non-zero then it closes the connection. When the client close input returns to zero then it reestablishes a connection as it did in the beginning. Note that the connection will not be established the first time the VI executes if the client close input is non-zero at that time. When the VI is not connected to a remote host then it outputs an invalid stream at its stm port so the other Intermediate Stream VIs know not to use the connection.

The listening stream is maintained as long as the listen close input remains zero or false. If the listen close becomes non-zero then it closes the listening stream, provided it is not currently connected to a remote host. The listening stream cannot be closed while a connection is established to a remote host. However, it will also not accept a new connection until the current connection is closed via the client close input. When the listen close input returns to zero then it begins to listen for connections as it did in the beginning. Note that it will not listen for connections the first time the VI executes if the listen close input is non-zero at that time. Note that it is generally unnecessary and is not recommended to close the listening stream. Hence, the listen close input should normally be zero.

The current state of the connection is output at the state port. The states and their integral values are:

Connection State	Value	Description
Not listening	0	The VI is neither connected nor listening for connections.
Not connected	1	The VI is listening for and attempting to accept a connection from a remote host but is not yet ready for communications.
Connected	2	The stream is fully connected and communication may occur over the stream.

If an error occurs then it will be reported to the Control and Simulation Loop. Note that only errors that occur in establishing the connection are reported. Once the connection is established this VI simply outputs the stream. It does not detect if the connection is lost due to an error. As a result, it will not close the connection if the remote host closes the connection or an established connection is lost. Instead, the other Intermediate Stream VIs, such as the Stream Read and Stream Write VIs will report an error if the connection is lost and when they do, the client close input of the Stream Answer VI should be set to a non-zero value to close the current connection.

The connection is closed when the VI is terminated or the client close input is non-zero. Note that the client close input must be maintained at a non-zero value to ensure that the connection remains closed. Otherwise the Stream Answer VI will reconnect.

Remote hosts are identified by a Universal Resource Identifier (URI), such as tcpip://remotehost:8000 or serial://remotehost:1?baud=57600. Control Prototyping Toolkit uses URI's for all its communications because it provides a uniform, extensible and flexible means of identifying the communication protocol to use and the associated communication parameters. Refer to Universal Resource Identifiers for more information.

Streams have an associated buffer that is independent of any buffering in the underlying protocol. The stream buffer is designed to maximize use of the available bandwidth. For example, if the Stream Write VI is configured to maximize throughput rather than minimize latency then it simply buffers data until the stream buffer is full and only then does it flush the stream buffer to the underlying communication channel. Similarly, the Stream Read VI simply returns data from the stream buffer. It only reads from the underlying communication channel when there is not enough data in the stream buffer, at which point it attempts to read enough bytes to fill the entire stream buffer.

Hint

When using the UDP protocol, the network interface card (NIC) from which datagrams are received may be specified using the nic option. Refer to the UDP Protocol for details. Unlike other protocols, it is also possible for two Stream Answer VIs to communicate with each other rather than requiring a Stream Answer and Stream Call VI.

Feedthrough Behaviour

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

Examples

	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.