navigation bar

Stream Call

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 Call VI establishes a connection to 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.

close is used to close the stream. 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 is the size of the buffer 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 is the order 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 is the size of the buffer 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 begins to connect to the remote host. It does not wait for the connection to be established, but continues the connection process each time the VI executes. Once a connection is established, it outputs the connection at its stream 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 cls input remains zero or false. If the cls input becomes non-zero then it closes the connection. When the cls 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 cls 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 current state of the connection is output at the state port. The states and their integral values are:

Connection State	Value	Description
Not connected	0	The stream is not connected.
Connecting...	1	The stream is in the process of being connected to the 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, it will be report 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 cls input of the Stream Call 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 cls input is non-zero. Note that the cls input must be maintained at a non-zero value to ensure that the connection remains closed. Otherwise the Stream Call VI will reconnect.

Remote hosts are identified by a Universal Resource Identifier (URI), such as tcpip://remotehost:8000 or serial://remotehost:1?baud=57600. RCP 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) through which datagrams are sent may be specified using the nic option. This option is particularly useful when broadcasting datagrams in order to restrict broadcast messages to a particular NIC. Without the nic option, most operating systems send broadcast messages through all the NICs. However, Windows 7 or later versions do not broadcast to all NICs in this case, but chooses one arbitrarily. Hence, specifying the nic option allows the NIC used for broadcast messages to be controlled. Refer to the UDP Protocol for details.

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.