Stream Formatted Read

Scans formatted data received over a stream. This block is intended for use in the main diagram.

Library

Description

The Stream Formatted Read block scans formatted data from a stream, much like fscanf scans 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 the format strings, refer to Format Strings for Scanning.

This block reads from the input stream and parses the textual data according to the given format string and then presents the parsed values at its outputs. 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 reading the text from the stream. The stream receive buffer must be large enough to hold all the text scanned while processing the format string. This size may need to be larger than expected because parsing the text often requires "looking ahead" additional characters to determine where the actual field ends.

If the input is invalid i.e., does not match the format string, then it returns zero at its err output and the inv output is set to true (non-zero). The flds output will reflect the number of fields that were parsed successfully and the number of data outputs that are valid. When a mismatch occurs between the input and the format string, the stream is not advanced. Hence, if this block is called again with a different format string it will rescan the same input. This feature makes it easier to recover from errors and to handle a selection of possible inputs. To skip to the end of a line to ignore invalid input, use a format string of " %*[^\n]\n", which ignores all characters in the input up to the next newline. Take careful note of the leading space character, which is needed to skip the whitespace at the end of the last valid line.

If the connection is closed at the peer then it returns zero at its err output and the cls output is set to true (non-zero).

If any other error occurs, then it returns a negative error code at its err output and the stream is not advanced. If the err output is negative then the stream cannot be rescanned. If no error occurs then the number of code units scanned is presented at the units output and the err output is zero.

For blocking streams, this block may wait while attempting to read from the stream. If parsing the input stream required "looking ahead" then the additional characters remain in the stream receive buffer until the next scan operation.

If the stream is non-blocking, then this block always returns immediately. It returns the number of code units scanned at the units output if all the text was parsed successfully. If the full format string could not be scanned without blocking, then zero is returned at its err output and the units output will also be zero. The flds output will reflect the number of fields parsed successfully without blocking. The Compare to Error block may be used to check for specific error codes. The Stream Poll block may be used to wait for more data to arrive or other events. If any other error occurs then the stream should be closed.

The number of fields parsed successfully and fully is indicated by the flds output.

The flds output may be non-zero even when the stream would have blocked or a mismatch occurs between the input and the format string. In this case, only those outputs corresponding to the successfully parsed fields will be valid. Outputs for fields not parsed successfully are indeterminate, and will not necessarily equal the last value successfully parsed.

The formatted text is treated as an atomic unit. It will never read part of the text. These semantics make it much easier to deal with streams in Simulink where it is difficult to deal with some outputs being valid while others are not. Hence, in non-blocking mode the data is not lost when scanning is incomplete due to not enough data yet being available. Instead, this block will rescan the text each time it is invoked until enough data has arrived to satisfy the format string. Note that the buffer size for the stream must be at least as large as the largest string of formatted text.

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

Helpful Hints

Skipping to the end of a line

To skip to the end of a line to ignore invalid input, use a format string of " %*[^\n]\n", which ignores all characters in the input up to the next newline. Take careful note of the leading space character, which is needed to skip the whitespace at the end of the last valid line.

Other uses of this block

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

Using HyperTerminal

Windows HyperTerminal may be used to send formatted text to the Stream Formatted Read 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 Read block to parse the text that gets sent from Windows HyperTerminal.

Input Ports

stm

A reference to the stream created by the Stream Call or Stream Answer block. If the stream is closed or is otherwise invalid then the negative error code -QERR_INVALID_STREAM is returned by the err output.

...

Subsequent input ports are used for variable field width and variable maximum code unit specifiers, such as "%.*s" or "%s[*] respectively in the format string.

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 contain the data parsed. The number of output ports is determined by the number of format specifiers, such as %lg, in the specified format string. If a format specifier contains an '*' after the '%' to suppress assignment to an output, then no output is created for that format specifier, and that field will not be included in the count of fields scanned. Variable-sized code unit specifiers cause input ports to be created in order to specify the maximum number of code units.

flds

An int32 value indicating the number of fields from the format string that were read from 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 read from the stream buffer or a mismatch occurred between the input and the format string. If an error occurs, then this value indicates the number of fields that could be read successfully, which may assist in locating the source of the error. This output always indicates the number of data outputs that are valid, even when an error occurs.

units

An int32 value indicating the number of code units read successfully from the stream. If it is zero then the stream would have blocked before the full format string was parsed. Do not use the data at the outputs unless this output is non-zero because the outputs do not preserve their previous value. If this output is zero and the err is also zero, then the flds output will indicate the number of fields that were scanned successfully and whose associated outputs are valid. The units output is only non-zero if all the fields were parsed successfully according to the format string.

inv

A Boolean value indicating whether the input was invalid according to the format string. The flds output will indicate the number of fields that were parsed successfully before the input failed to match the format string. This output is true (non-zero) if the input did not match the format string. Otherwise it is false (zero). Note that when the input fails to match the format string, the err output will be zero and the inv output will be true, so that only stream errors, such as the connection being lost, are reported at the err output. This distinction is particularly important because in the event that the input fails to match the format string, the stream is not advanced at all and can be rescanned using a new format string.

cls

A Boolean value indicating whether the stream was closed gracefully at the peer. This output is true (non-zero) if the stream was closed at the peer and false (zero) otherwise. The err output is zero if the stream is closed at the peer.

err

An int32 value indicating whether the formatted text was read from the stream buffer successfully. For blocking streams, this value will be zero 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 read from the stream buffer then zero is output and the units output will also be zero. If the input does not match the format string then zero is also output from this port and the inv output will be true (non-zero). 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

The Stream Formatted Read block outputs signals of any of the built-in Simulink data types at its data outputs. The data type is determined by the format specifiers in the format string. Fixed point is not currently supported.

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

Parameters and Dialog Box

Format string

The format string used to parse the data. Refer to the Format Strings for Scanning 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 input.

Maximum number of code units to scan

This parameter restricts the total number of code units read from the stream. This limit is a hard limit. The total number of code units read from the stream will never exceed this limit, even if a field is truncated.

Targets

See Also

• Format Strings for Scanning
• Stream Formatted Write 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.