Stream Formatted Write

Sends formatted text over a stream. This block is intended for use in the main diagram.

Library

Description

The Stream Formatted Write block prints formatted text over a stream, much like fprintf prints to a file. The operation of this block is affected by the blocking mode of the stream connected to its input. Streams have two modes: blocking (the default) and non-blocking. If a Stream Call or Stream Answer block is used to create the stream, then the stream will be non-blocking. If a Stream Connect or Stream Accept block is used to create the stream then the blocking mode of the stream is determined by the Stream Connect or Stream Listen block.

For a description of format strings, refer to Format Strings for Printing.

This block formats its inputs according to the given format string and then writes the formatted textual result to the stream buffer. It attempts to store all of the formatted text in the stream buffer. It uses the current character format of the stream to determine the character format for the text (UTF-8, UTF-16 or UTF-32). If the stream has been configured to swap bytes then this block will swap the order of the bytes within each Unicode character when storing the text in the stream buffer. If there is enough room available in the stream buffer then it stores the text in the buffer and returns immediately. If the Optimize parameter is set to minimize latency then it will also flush the stream each time that it executes. Otherwise, it only flushes the stream buffer to the underlying communication channel when the stream buffer is full. The size of the stream buffer is set by the Send buffer size parameter of the Stream Call or Stream Answer block that created the stream.

If an error occurs, then it returns a negative error code at its err output. If the connection is closed it is considered an error condition. The Compare to Error block may be used to check for specific error codes. If the stream is not valid because it is not yet connected, the err output will be zero since this condition is expected and the validity of the stream may be checked using the con output of the Stream Call or Stream Answer blocks.

The formatted text is treated as an atomic unit. It will never write part of the text to the stream buffer. These semantics make it much easier to deal with streams in Simulink where it is difficult to deal with "parts" of text. Note that the buffer size for the stream must be at least as large as the largest string of formatted text or -QERR_STREAM_BUFFER_TOO_SMALL is returned by the err output.

This block does not support two threads calling Stream Formatted Write or Stream Write at the same time. However, Stream Formatted Write or Stream Write may be called by another thread at the same time as Stream Read.

Helpful Hints

Although it is intended for use in the main diagram with the other Intermediate stream blocks, the Stream Formatted Write block may be used with the Advanced stream blocks, even in an asynchronous thread.

Using HyperTerminal

Windows HyperTerminal may be used to receive the formatted text streamed using the Stream Formatted Write block. Simply configure HyperTerminal to use the TCP/IP protocol on localhost and port 18,000. Another port may be used, but the default port for the Stream Call block is 18,000 so it makes it easier. Then select the Call/Wait for a Call menu item to cause HyperTerminal to listen on port 18,000 for a client connection.

In your model, connect as a client to the machine running Windows HyperTerminal on port 18,000. Use the Stream Formatted Write block to format the text that gets sent to Windows HyperTerminal.

Input Ports

stm

A reference to the stream created by the Stream Call or Stream Answer block. If these blocks have not established a connection the err output of the Stream Write block will be zero.

...

Subsequent input ports contain the data to be formatted. The number of input ports is determined by the number of format specifiers, such as %lg, in the specified format string. The %n format specifier does not produce an input port. Instead it causes an output port to be created. All other valid format specifiers cause corresponding input ports to be created. Variable-sized field widths, precisions and code unit specifiers also cause input ports to be created in order to specify the field width, precision or maximum number of code units. Inputs corresponding to string or variable dimension format specifiers may be variable-size signals. Refer to Variable-Size Signals for more information on variable-size signals.

Output Ports

stm

A reference to the stream. This output is merely a copy of the stm input. Providing this output makes it much easier to establish the execution order of Stream blocks in the diagram because Simulink generally executes daisy-chained blocks in sequence.

...

Subsequent output ports, with the exception of the last two ports, are used for %n specifiers in the format string, which produce the number of code units processed up to that point in the format string.

flds

An int32 value indicating the number of fields from the format string that were written to the stream buffer successfully and fully. This number may be less than the number of fields defined in the format string if the maximum number of code units was reached before all the fields were written to the stream buffer. If an error occurs, then this value indicates the number of fields that could be written successfully, which may assist in locating the source of the error.

units

An int32 value indicating the number of code units that were written to the stream buffer successfully and fully. This number will always be less than or equal to the maximum number of code units defined in the dialog parameters. If the data could not be written to the stream buffer without blocking then this output will be zero, as will the err output.

peer

A Boolean value indicating whether an error has occurred due to the peer not yet being designated. For a UDP server, the client is generally unknown until the first receive operation has been completed successfully, because the UDP protocol is a connection-less protocol. Not knowing the peer means no data will be sent. However, it is not regarded as a fatal error because the stream does not need to be closed in this case. It merely indicates that no client has "connected" yet by sending a datagram to the server. The UDP server should continue listening on the port and attempting to receive data. This output can be used to determine why no data has been sent (see the units port) when there are no other errors and the operation should not have blocked.

err

An int32 value indicating whether any errors occurred. It is zero if no errors occurred and a negative error code otherwise. 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. To check for errors in general, simply test whether the output is non-zero. Note that the QERR_NO_DESIGNATED_PEER error is not reported at this output. It is signalled at the peer output instead since it is not regarded as a fatal error requiring closure of the stream. The QERR_WOULD_BLOCK error is also not reported at this output because it simply indicates that the data could not be sent without blocking. The units output may be used to determine whether the data was actually written to the stream buffer.

Data Type Support

For scalar quantities, the Stream Formatted Write block accepts signals of any of the built-in Simulink data types at its data inputs. Fixed point is not currently supported.

For array quantities, as indicated by a dimension specifier in the format string, the Stream Formatted Write block only accepts signals of the data type corresponding to the format specifier at that port.

Parameters and Dialog Box

Format string

The format string used to format the data. Refer to the Format Strings for Printing page for a description of the format string. This parameter is treated as a string literal. It is not evaluated. Hence, do not enclose the format string in quotes unless you wish the quotes to appear in the output.

Maximum number of code units to print

This parameter restricts the total number of code units written to the stream. This limit is a hard limit. The total number of code units written to the stream will never exceed this limit, even if the output for an input port is truncated or all the input ports have not been included in the output.

Optimize for

Determines whether the block is optimized for maximizing throughput or minimizing latency. If this option is set to maximize throughput, then the block only flushes the stream buffer to the underlying communication channel when when the stream buffer is full. In this way, as much data as possible can be transferred in each packet for packet-based protocols such as TCP/IP or UDP.

If this option is set to minimize latency then it flushes the stream buffer to the underlying communication channel each time the block executes. Doing so minimizes the time between when the data is generated and when it is sent to the remote host, but it may under-utilize the communications bandwidth since packets may not be full when they are sent.

Targets

See Also

• Format Strings for Printing
• Stream Formatted Read block
• Stream Print block
• Stream Answer block
• Stream Call block
• Stream Write block
• Stream Read block
• Intermediate Communications
• MATLAB Stream Functions
• Communications Using the C Language

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

Link to this page.