Stream Print

Prints formatted data over a stream.

Library

QUARC Targets/Communications/Advanced

Description

The Stream Print block prints formatted data 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. The blocking mode of the stream is determined by the Stream Connect or Stream Accept block which created the stream. The Stream Print block cannot be used with streams created using the Stream Listen block.

For a description of the 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. The data is not written to the actual communication channel until the stream is flushed using the Stream Flush block or there is no more room available in the stream buffer. 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.

For blocking streams, this block may wait while attempting to flush the stream buffer. All the text will be consumed and the number of code units printed is returned at its err output. Some of the text may remain in the stream buffer and not be sent until the next time the Stream Flush block is called or there is no more room available in the stream buffer. If an error occurs then the error code is returned at its err output and the stream should be closed.

If the stream is non-blocking, then this block always returns immediately. It returns the number of code units printed if all the text was sent successfully. If the full text could not be sent without blocking, then -QERR_WOULD_BLOCK is returned at its err output. The Compare to Error block may be used to check for specific error codes. The Stream Poll block may be used to wait or poll for space in the stream buffer to store the text or other events. If any other error occurs then the stream should be closed.

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 Print or Stream Flush at the same time. However, Stream Print or Stream Flush may be called by another thread at the same time as Stream Receive.

Helpful Hints

The Stream Formatted Write block has similar functionality to Stream Print, but is easier to use. Although it is an Intermediate stream block, it may be used with the Advanced blocks also.

Using HyperTerminal

Windows HyperTerminal may be used to receive the formatted text streamed using the Stream Print 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 Connect 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 Print block to format the text that gets sent to Windows HyperTerminal.

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

err

An int32 value indicating whether the formatted text was written to the stream buffer successfully. For blocking streams, this value will be the number of code units printed unless an error occurs. If an error occurs then this value is a negative error code. If the stream is non-blocking and the formatted text could not be written to the stream buffer then -QERR_WOULD_BLOCK is output. 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 use the Compare to Zero block to check whether err output is less than zero.

Data Type Support

For scalar quantities, the Stream Print 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 Print 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.

Targets

See Also

• Format Strings for Printing
• Stream Listen block
• Stream Connect block
• Stream Send block
• Stream Flush block
• Stream Receive block
• Advanced 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.