Collapse
CollapsingX
  • - or -

TextReader step overview


The TextReader step is used to read information from text files stored on your runtime platform or a shared network drive. Typical uses for the TextReader step include obtaining configuration information from an INI file, or obtaining information about product variants from a CSV file.

The TextReader step will be skipped at design-time when Matrox Design Assistant is running in emulation mode.

Procedure for using the TextReader step

The following is a basic procedure for using the TextReader step:

  1. Specify the path of the folder containing the text file to be read. The default folder is {PATH("DA Documents")}\\SavedTextFiles. To determine what this evaluates to on your runtime platform, see the PATH function. For information on specifying a different folder, see the Specifying a path section in Appendix A: Expression syntax.

  2. Specify the File Name (including file extension) of the text file to be read.

  3. Choose the Operation to perform.

Operations

The Operation property of the TextReader step allows you to specify how much of the text file to read. You can use different operations to handle very large or very small files in different ways. Some operations, such as the ReadUpToExpectedText operation, facilitate reading structured text files, such as files that resemble INI files with sections indicated using header tags (for example, "[VERSION]").

A read operation will always start from the character position where the previous read operation on the file stopped. This starting point does not automatically return to the first line when the end of the file is reached. To read from the first line of the file, use the MoveToLine operation.

There are 7 operations that the TextReader step can perform:

  • The ReadToEnd operation will read until the operation reaches the end of the file.

  • The ReadLines operation will read the number of lines that you specify in the NumberOfLines property.

  • The ReadCharacters operation will read the number of characters that you specify in the NumberOfCharacters property.

  • The ReadUpToExpectedText operation will read all the data in the file until the characters in the ExpectedText property have been reached.

  • The MoveToLine operation will move the starting point of the next read operation to the beginning of the line that you specify in the Line index property.

  • The Open operation will open the file.

  • The Close operation will close the file. This also returns the starting point for read operations on the file.

The Open operation will be performed automatically if the file is not already open in your project. Opening a file can take a substantial amount of time, particularly if that file is being accessed over a network. It can be useful to execute an Open operation outside of the main loop so that this delay does not interfere with inspection. Once a file has been opened for reading (automatically or manually), it will be kept open until your project is terminated, or the file is closed manually using the Close operation.

Note that other editors might not be able to write to the file until it has been closed.

Accessing results

You can access the results of a TextReader step using the following outputs:

  • Text is a string containing all of the text. Line breaks are represented as "\r\n" .

  • Lines is a string array containing each line of the text in sequence as a separate element. For more information on working with arrays, see Chapter 27: Using arrays.

Processing strings

You can use expressions to parse the results of a TextReader step. The STRING function group in particular contains several functions which perform common tasks required for breaking complex strings into useful values. The following are typical use cases:

  • Use the TRIM function to remove leading and trailing whitespace to prepare a string for use with the STRINGTONUMERIC function.

  • Use the SPLITSTRING function to create an array of strings from a single string containing individual values separated by a delimiting character (for example, a comma in a CSV file). For more information about reading values from a CSV file, see the Reading CSV files subsection of this section.

  • Use the FILTER function with the CONTAINSSTRING function or the STARTSWITH function to create an array of only the lines that contain some specified text (for example, a particular setting heading such as "JobName=").

Error handling and complex expressions

Your project might need to handle unexpected formatting in text files, such as extra spaces between words, empty lines at the end of a file, or spelling mistakes. If you do not account for these types of situations, your project might exhibit unintended behavior. This can include encountering runtime errors (for example, attempting to access an array that is empty, or attempting to use the STRINGTONUMERIC function with a string that contains non-numeric characters).

The following techniques can be used in expressions to handle unexpected results from a TextReader step:

  • Use the IF function to verify that a string exists and is formatted correctly before attempting to use it with another function (for example, using the ISVALID function to verify that a line number exists in the output of a TextReader step).

  • Use operators from the LOGIC function group to verify that a file is not empty, or has a specific number of lines. For example, you might want a Value element in the operator view to display either a product name stored in the first line of a configuration file, or an error message if the TextReader step found that the file was empty. To do so, you can set the Text property of the Value element to the following expression:

    {IF(TextReader.LineCount > 0, TextReader.Lines(1), "ERROR! FILE NOT READ/FILE IS EMPTY!")}

    In some cases, you might want to perform similar checks on the results of ARRAY functions, such as FILTER and SELECT.

  • Use the ISNUMERIC function to determine if any non-numeric characters are present before using the STRINGTONUMERIC function. For example, a Store step might set a numeric variable using the following expression:

    IF(ISNUMERIC(TextReader.Lines(6)), TONUMERIC(TextReader.Lines(6)), -1)

    In this example, -1 is used to indicate that there was an error while attempting to set the variable.

  • Use the SPLITSTRING function to remove any illegal characters from a string before attempting to use it. For example, a Store step might set a string variable to be used as part of a file name, using the following expression:

    {ARRAYTOSTRING(SPLITSTRING(TextReader.Lines(39),"\\/.:*?\'\x0022"))}

    The SPLITSTRING function parses a string to a string array, using all of the characters you specify as delimiters (in this example, all characters that are illegal in file names under Microsoft Windows). The ARRAYTOSTRING can then be used to convert this array back into a string which does not include the illegal characters.

Reading CSV files

The TextReader step can be used to read comma separated value (CSV) files exported from spreadsheet applications and other software. One common use for this feature is to change inspection settings when switching between product variants that vary only in details that can be defined using strings and numbers. For more information on selecting a strategy for inspecting similar products, see the Strategies for inspecting product variants section in Chapter 54: Switching products to inspect.

This subsection describes the procedure for using an example CSV file to define inspection settings across product variants. Once this procedure is completed, the user will be able to select a product by name in the operator view to change the nominal and tolerance values used for inspection. These values will be obtained from a CSV file when the project is started.

This procedure uses variables and several functions from the ARRAY and STRING groups. You can access a function's documentation directly from Matrox Design Assistant by pressing F1 while highlighting that function in the Advanced editor.

In this example, third-party software has been used to create the following spreadsheet:

Part Number

Product Name

Length

Length Tolerance

Height

Height Tolerance

X3456

3mm Widget

3.00

0.25

5.25

0.25

X4567

4mm Widget

4.00

0.25

5.25

0.25

X7845

5mm Widget

5.00

0.25

5.25

0.25

X8885

6mm Widget

6.00

0.25

5.25

0.25

CSV files can follow many different formatting standards. In this example, the spreadsheet has been exported as a CSV file with the following contents.

X3456,3mm Widget,3.00,0.25,5.25,0.25,
X4567,4mm Widget,4.00,0.25,5.25,0.25,
X7845,5mm Widget,5.00,0.25,5.25,0.25,
X8885,6mm Widget,6.00,0.25,5.25,0.25,

As part of the procedure, the TextReader step will read an example CSV file into your project. You will access the output of this step as a string array with the following elements.

Index

String

1

"X3456,3mm Widget,3.00,0.25,5.25,0.25,"

2

"X4567,4mm Widget,4.00,0.25,5.25,0.25,"

3

"X7845,5mm Widget,5.00,0.25,5.25,0.25,"

4

"X8885,6mm Widget,6.00,0.25,5.25,0.25,"

Use the following procedure to set up your project to switch product variants based on the values read from the CSV file.

Note that the Height and Height Tolerance values will not be used in this example.

  1. Create the following variables, using the Manage Variables dialog:

    Data type

    Variable name

    Description

    string array

    ProductNumbers

    Used to store the list of product numbers.

    string array

    ProductNames

    Used to store the list of product names.

    string array

    ProductLengths

    Used to store the list of product lengths.

    string array

    ProductLengthTolerances

    Used to store the list of product length tolerances.

    string

    DropDownSelect

    Used to store the current product name, selected by the user from a DropDownList element in the operator view.

    numeric

    DropDownSelectIndex

    Used to store the array index of the product name selected by the user in the operator view. This corresponds to the product's row in the original CSV file.

    numeric

    CurrentProductLengthNumeric

    Used to store the currently selected product's length as a number.

    numeric

    CurrentProductLengthToleranceNumeric

    Used to store the currently selected product's length tolerance as a number.

  2. Add 2 TextReader steps in a subflowchart that executes only when the project starts. You might also want to execute this subflowchart elsewhere in your project (for example, from a button labeled "Reload" in the operator view) so that values can be updated at runtime without restarting your project.

  3. Configure the first TextReader step to access the CSV file and perform the ReadToEnd operation.

  4. Configure the second TextReader step to access the CSV file and perform the Close operation.

  5. Add a Store step after the TextReader steps. Configure the Store step to store ProductNumbers, ProductNames, ProductLengths, and ProductLengthToleraces as {SELECT(ReadFileToEnd.Lines,ELEMENTAT(SPLITSTRING(Item,","),X))}, where X is the column number of the relevant entry in the spreadsheet:

    This expression uses the SELECT and SPLITSTRING functions to parse each line for the entry in a single column of the CSV file. For example, ProductNames will now have the following contents:

    Index

    String

    1

    "3mm Widget"

    2

    "4mm Widget"

    3

    "5mm Widget"

    4

    "6mm Widget"

  6. Create another subflowchart called UpdateCurrentProductValues and add a Store step to it.

  7. Add a DropDownList element to the operator view. Using Configuration pane, configure the DropDownList element as follows:

    • Set the Input type property to String.

    • Set the Bound target property to Variables.DropDownSelect.

    • From the DYNAMIC tab of the LIST OF VALUES page, set the List of names and List of values properties to {Variables.ProductNames}.

    • From the EXECUTE FLOWCHART page, set the DropDownList element to execute UpdateCurrentProductValues when the value changes.

    The DropDownList element will now allow the user to select product variants by name. The user's selection will be stored in the DropDownSelect variable.

  8. Configure the Store step in the UpdateCurrentProductValues subflowchart to do the following:

    • Set DropDownSelectIndex to INDEXOF(Flowcharts("MainFlowchart").Variables.ProductNames, Item = Flowcharts("MainFlowchart").Variables.DropDownSelect).

      This expression uses the INDEXOF function to find the index of the currently selected product in ProductNames. This index can be used to find the value for this product in the other arrays (such as ProductLengths).

    • Set CurrentProductLength to TONUMERIC(Flowcharts("MainFlowchart").Variables.ProductLengths(Flowcharts("MainFlowchart").Variables.DropDownSelectIndex)).

      This expression uses the TONUMERIC function to convert the nominal length for the currently selected product into a numeric data type so it can be used as an inspection setting.

    • Set CurrentProductLengthTolerance to TONUMERIC(Flowcharts("MainFlowchart").Variables.ProductLengthTolerances(Flowcharts("MainFlowchart").Variables.DropDownSelectIndex)).

      This expression uses the TONUMERIC function to convert the length tolerance for the currently selected product into a numeric data type so it can be used as an inspection setting.

Once this procedure is complete, you will be able to use the variables CurrentProductLength and CurrentProductLengthTolerance as inspection settings in your project. They will automatically be updated when the user selects a new product variant in the operator view.

Handling unexpected formatting

The CSV file used in this example is consistently formatted (for example, it contains the expected number of lines, and elements do not contain any extraneous spaces or illegal characters). In some cases, failure to accommodate unexpected formatting can cause your project to throw a runtime error and terminate. You will typically need to include additional steps and complex expressions that either modify strings to fit the expected formatting, or notify the user that the CSV could not be read. For more information, see the Error handling and complex expressions subsection of this section.