CL Stream Listen

Owning Palette: Communications/Advanced

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

Description

The CL Stream Listen VI creates a stream that listens for connections from remote hosts. The stream is created each time the VI executes. Streams have two modes: blocking (the default) and non-blocking. This VI returns immediately regardless whether the stream is blocking or non-blocking.

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.

uri identifying the communication channel upon which to listen for connections from remote hosts, and the associated communication parameters. For example, tcpip://localhost:18000?backlog=10 listens for connections on TCP/IP port 18000 and allows up to 10 client connections to be queued while awaiting acceptance by a CL Stream Accept VI.

Non-blocking, check this port to make the stream non-blocking. In this case, all VIs using the stream become nonblocking; this VI will return immediately but any CL Stream Accept VI using this stream will not wait for a connection to be accepted. Instead, whenever the CL Stream Accept VI would otherwise wait, the error code `-QERR_WOULD` is returned.

Outputs

stream out reference to the stream. This reference is always valid but will not refer to a listening stream if the stream could not be created. It has a data type of t_stream_ptr. 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 Send, CL Stream Flush or CL Stream Receive VI. Attempting to do so will result in an error being returned by that VI.

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

However, in non-blocking mode, any CL Stream Accept VI using the stream will also be non-blocking. Furthermore, connections accepted from remote hosts will be non-blocking. Whenever a CL Stream Accept 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 a connection to be accepted or other events.

If the stream is created successfully then the stream out output refers to the connected stream. This stream signal is passed as an input to CL Stream Accept VIs to refer to the stream. In this case, the error out output will be zero.

If the stream could not be created then the error out output will be a negative error code. The stream out output is never zero, even when the stream cannot be created, because it is a reference to the stream rather than the stream handle itself. Hence, it cannot be used directly to determine whether the stream is valid.

The communication channel used for streams is identified by a Universal Resource Identifier (URI), such as tcpip://localhost:18000 or serial://localhost: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.

When the URI is specified as a dialog parameter and is not evaluated then the URI is configuration-dependent.

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 CL Stream Listen VIs to communicate with each other rather than requiring a CL Stream Listen and CL Stream Connect VI.

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 Connect	The CL Stream Connect VI establishes a connection to a remote host. The connection is made each time the VI executes.
	CL Stream Flush	The CL Stream Flush VI writes the data in the stream buffer to the underlying communication channel.
	CL Stream Accept	The CL Stream Accept VI accepts a connection from a remote host.
	CL Stream Poll	The CL Stream Poll VI polls for events associated with the connected stream.