Scan

Scans input from the QUARC Console.

Library

Description

The Scan block scans formatted text entered in a QUARC Console, much like scanf scans stdin. This block is always blocking and therefore should never be used in the main diagram. Instead, it should be used in an asynchronous thread created using an Asynchronous Thread block. It is not currently supported in normal simulation although this support may be added in the future (do not check the Active during normal simulation option).

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

This block reads from the QUARC Console and parses the textual data according to the given format string and then presents the parsed values at its outputs. The QUARC Console requires that the Enter key be pressed before the line entered is sent to the model. The stream buffer must be large enough to hold the text for each field 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 only advanced up to end of the last matching field or character scanned. Hence, if this block is called again with a different format string it will rescan the same input starting at the first character that did not match the format string. To skip to the end of a line to ignore invalid input, use a format string of " %*[^\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 any other error occurs, then it returns a negative error code at its err output and the stream is not advanced. However, the stream cannot be rescanned. If no error occurs then the number of code units scanned is presented at the err output.

This block does not support two threads calling Scan at the same time. However, Scan may be called by another thread at the same time as Print.

Important Notes

Console must be specific to model

The QUARC Console must be opened for the specific model to which its input should be directed. Opening a QUARC Console using the Console for All option will not work!

May need to press Enter to terminate model

Because standard I/O is always blocking on the Windows target, it may be necessary to press Enter in a QUARC Console before an asynchronous thread containing a Scan block can terminate. This restriction can prevent other block's termination functions from executing until the asynchronous thread has exited.

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]", 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.

Input Ports

...

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

...

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

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 only advanced up to the end of the last matching field or character scanned and can be rescanned from that point onward using a new format string.

err

An int32 value indicating whether the formatted text was read from the Console successfully. This value will be the number of code units read unless an error occurs. If an error occurs then this value is a negative error code. If the input does not match the format string then 0 is 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 Scan 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 Scan 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 Console. This limit is a hard limit. The total number of code units read from the Console will never exceed this limit, even if a field is truncated.

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 from its input.

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 -1 because this block is typically used in a Function Call Subsystem attached to an Asynchronous Thread block.

Active during normal simulation

Indicates whether this block should execute during normal simulation. This option should not be checked because this feature is not presently supported.

Targets

See Also

• Format Strings for Scanning
• QUARC Console - Model Standard I/O
• Print block

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

Link to this page.