CL Stream Connect

Owning Palette: Communications/Advanced

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

Description

The CL Stream Connect VI establishes a connection to a remote host. The connection is made each time the VI executes.

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.

send buffer size in bytes 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 CL 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 to which to connect. This port identifies the communication protocol and associated parameters. For example, tcpip://quanser-dev:18000 connects to the remote host called quanser-dev using TCP/IP on port 18000.

non-blocking, check this port to make the stream non-blocking. In this case, all VIs using the stream become nonblocking; this VI will not wait for the connection to be established and Stream VIs using this stream will not wait for data to be sent or received. Instead, whenever a VI would otherwise wait, the error code `-QERR_WOULD` is returned.

receive buffer size in bytes 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 CL 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 out 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 cannot be plotted and may only be connected to the stream out input of one of the Stream VIs. It may not be connected to a CL Stream Accept VI. Attempting to do so will result in an error being returned by the CL Stream Accept VI.
	would block? is true if the operation would have blocked waiting to connect to the server, and false otherwise. This output is only valid when the stream has been configured as non-blocking. For blocking streams, this output is always false.
	err is an int32 error code indicating the results of the operation. If the connection is successfully established, then this output will be zero. If the stream is non-blocking and the connection is in progress then `-QERR_WOULD` is output. Otherwise another negative error code is returned.

Details

The CL Stream Connect VI establishes a connection to a remote host. The connection is made each time the VI executes. Streams have two modes: blocking (the default) and non-blocking.

In non-blocking mode, this VI returns immediately. If the connection has been established, then the err output will be zero. If the connection is pending then the error code -QERR_WOULD is returned. If the connection failed then another negative error code is returned. Furthermore, all Stream VIs using the stream also become non-blocking. Whenever a Stream VI would otherwise wait, the error code -QERR_WOULD is returned instead. When combined with a state machine, non-blocking mode is suitable for periodic tasks because it does not interfere with the sampling rate. The CL Stream Poll VI may be used to wait or poll for the connection to complete or other events.

If the connection is successfully established then the stream out output refers to the connected stream. This stream signal is passed as an input to other Stream VIs to refer to the stream. In this case, the err output will be zero.

If the connection cannot be successfully established then the err output will be a negative error code. The stream out output is never zero, even when the connection cannot be established, because it is a reference to the stream rather than the stream handle itself. Hence, it cannot be used directly to determine whether the connection has been established.

Streams must be closed using the CL Stream Close VI when they are no longer in use. A stream that is not closed will remain open until the VI terminates.

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, the CL Stream Write VI 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 CL 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 Advanced Stream Example

Targets

Target	Supported	Comments
RCP Windows (64-bit) Target	Yes	Fully supported.

navigation bar

	CL Stream Close	The CL Stream Close VI closes the stream connected using CL Stream Connect.
	CL Stream Accept	The CL Stream Accept VI accepts a connection from a remote host.
	CL Stream Flush	The CL Stream Flush VI writes the data in the stream buffer to the underlying communication channel.
	CL Stream Listen	The CL Stream Listen VI creates a stream that listens for connections from remote hosts.
	CL Stream Poll	The CL Stream Poll VI polls for events associated with the connected stream.