Stream Answer

Listens for and accepts a connection from a remote host. This block is intended for use in the main diagram.

Library

QUARC Targets/Communications/Intermediate

Description

The Stream Answer block 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 model. However, as a result, communication protocols that do not support non-blocking I/O are not supported by the Intermediate Stream blocks.

The first time the block 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 block 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 blocks to refer to the stream.

The connection is maintained as long as the ccls input remains zero or false. If the ccls becomes non-zero then it closes the connection. When the ccls 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 block executes if the ccls input is non-zero at that time. When the block is not connected to a remote host then it outputs an invalid stream at its stm port so the other Intermediate Stream blocks know not to use the connection.

The listening stream is maintained as long as the lcls input remains zero or false. If the lcls 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 ccls input. When the lcls 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 block executes if the lcls input is non-zero at that time. Note that it is generally unnecessary and is not recommended to close the listening stream. Hence, the lcls input should normally be zero.

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

If an error occurs then the err output will be a negative error code. Otherwise the err output will be zero. Note that only errors that occur in establishing the connection are reported. Once the connection is established this block 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 blocks, such as the Stream Read and Stream Write blocks will report an error if the connection is lost and when they do, the ccls input of the Stream Answer block should be set to a non-zero value to close the current connection. Typically, a Compare To Zero block is used with the other Intermediate Stream blocks to detect if an error occurs (if the err output of these blocks is less than zero) and the output of the Compare To Zero block is fed to the ccls input of the Stream Answer block. Doing so ensures that the connection is closed when an error occurs and that the connection is reestablished as soon as possible.

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

Remote hosts are identified by a Universal Resource Identifier (URI), such as tcpip://remotehost:8000 or serial://remotehost:1?baud=57600. QUARC 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.

The URI may be specified in the dialog parameters or via an input port. Which option is used is determined by the Source of URI parameter. When the URI is specified via an input, the input is typically driven by a Model Argument block, which allows a model argument to be used to assign the URI at runtime.

When the URI is specified as a dialog parameter and is not evaluated then the URI is configuration-dependent. A separate URI may be entered for each model configuration as well as for normal simulation. Thus, it is possible to employ a different URI for each target, without making a new diagram. The URI that is entered becomes the URI for the currently active configuration when the Simulation mode is set to External. It becomes the URI for normal simulation when the Simulation mode is set to Normal.

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

Helpful Hints

Firewall

If remote clients will be communicating with the server then be sure to configure the server machine's firewall to allow incoming access on the port being used.

Multiple NICs and UDP

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 blocks to communicate with each other rather than requiring a Stream Answer and Stream Call block.

Input Ports

lcls

Used to close the listening stream. Setting this input to a non-zero value will cause the block 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 block will begin accepting connections from remote hosts. The block will continue listening as long as this input is zero. This input is ignored if the block is currently connected to a remote host. In general, this input should always be zero.

ccls

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.

uri

A string specifying the URI upon which to listen for client connections. The string must be a null-terminated vector of characters represented as a vector of uint8 quantities. It may be variable-sized. This string is typically provided either directly or indirectly by a Model Argument block or String Constant block.

This input is only available if the Source of URI parameter is set to External input port. Refer to the documentation below on the Source of URI parameter for details.

Output Ports

stm

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 cannot be plotted and may only be connected to the stm input of one of the Stream blocks. It may not be connected to a Stream Accept block. Attempting to do so will result in an error being returned by the Stream Accept block.

con

A uint8 state code indicating the current status of the connection. The different connection states and their values are given in the table above in the Description section.

err

An int32 error code indicating the results of the operation. If there are no errors during the establishment of a connection, then this output will be zero. The -QERR_WOULD_BLOCK error is never output at this port, even though non-blocking I/O is used, because this condition is not considered an error by the block. Otherwise another negative error code is returned. See Error Codes for the different error codes and their values. Use the Compare to Error block rather than the error code itself to check for specific error codes.

Parameters and Dialog Box

Source of URI

Indicates whether the URI should be determined from the dialog parameters or an input port. If this field is set to Specify via dialog (do not evaluate) then the URI is specified via the URI upon which to listen parameter. In this case, the URI is not evaluated as a MATLAB expression but is interpreted as a literal string. However, format specifiers are recognized. Refer to qc_perform_substitutions for a list of the format specifiers available.

If format specifiers which change frequently, such as '%{time}' or '%{instance}', are used in the URI then the Stream Answer block cannot be placed in a referenced model, because the URI will change from the time the code is built to when the code is run. As a result, Simulink will insist that the code be rebuilt because block parameters in referenced models are inlined. Instead, specify the source of the URI as External input port and pass the URI from the top-level model. Use a String Constant block in the top-level model to generate the URI.

If this field is set to Specify via dialog (evaluate) then the URI is also specified via the URI upon which to listen parameter. However, in this case, the URI is evaluated as a MATLAB expression. This option is convenient for using a variable in the MATLAB workspace for the URI.

If this field is set to External input port then the URI upon which to listen parameter is ignored and an extra input port is provided which determines the URI.

URI upon which to listen (tunable offline)

The 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 the block. This field is only used if the Source of URI parameter is set to Specify via dialog (do not evaluate) or Specify via dialog (evaluate). Refer to Universal Resource Identifiers for more information about URIs and the communications protocols supported by QUARC.

Send buffer size in bytes (tunable offline)

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

Receive buffer size in bytes (tunable offline)

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

Byte ordering (tunable offline)

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.

Sample time

The sample time of the block. A sample time of 0 indicates that the block will be treated as a continuous time block. A positive sample time indicates that the block is a discrete time block with the given sample time.

A sample time of -1 indicates that the block inherits its sample time. Since this is a source block, only inherent the sample time when it is placed in a conditionally executed subsystem, like a Triggered Subsystem, Enabled Subsystem, Function Call Subsystem or in a referenced model.

To use the fundamental sampling time of the model, set the sample time to qc_get_step_size, which is a QUARC function that returns the fundamental sampling time of the model.

The default sample time is set to qc_get_step_size.

Active during normal simulation (tunable offline)

Indicates whether this block should execute during normal simulation. If this option is not checked then the block will not listen for or accept connections during normal simulation. This parameter has no effect on generated code.

Targets

See Also

• Stream Call block
• Stream Read block
• Intermediate Communications
• MATLAB Stream Functions
• Communications Using the C Language

Copyright ©2024 Quanser Inc. This page was generated 2024-04-16. Submit feedback to Quanser about this page.

Link to this page.