Text

Tag: Integration

The Text block can generate a file based on a template using values of variables received to input ports, and extract values from an input file in order to send them to output ports. Its configuration is based on a template file — usually a sample of some program’s input or output.

Introduction

The Text block is a custom file processor that can read data from text files and change their contents. It is primarily used to create input and output adapters for integrating third-party applications in pSeven workflows (see the Integration Basics tutorial).

If the integrated application requires an input file with parameters, the Text block uses a template file (a sample of input) to generate input files at workflow run-time. It reads template contents, replaces specified areas with values received to input ports, and outputs a new file with changed parameters. This file is then sent to the block that launches the application (usually the Program block).

Application output can be parsed with the Text block if the application is able to save its results to a text file. Also it can be used with an application that sends results to the standard output (prints to the command prompt window), because this output is easily redirected to a file. The Text block receives the output file from the block that launches the application, reads data from specified locations in the file, and sends data values to output ports. In this case, the template file is not required at the run-time, however having a sample of output is convenient when configuring the block.

General logic of the Text block is always the same:

  • Get values of input variables (received to ports) and the input file.
  • Copy the input file to memory and perform operations over this copy (write input values, get values of output variables).
  • Send values of output variables and the file (changed copy) to output ports.

Two typical cases of using the Text block were outlined above. However, these are not some presets — rather they are two commonly used combinations of settings (sections Generate Program Input and Parse Program Output explain them in more detail). Other configurations are also possible — for example, the block can read and write to the same file at once, if needed.

Text blocks can be used, for example, in an optimization workflow that uses an external solver for function evaluations. One block receives values of variables from Optimizer and creates an input file for the solver; the other receives solver’s output, reads result values and sends them to Optimizer (see Integrated Component Optimization).

With the Text block, you can also generate complex text reports, create custom configuration files for your workflows, and perform other text-related tasks. It also supports Python scripting and allows to combine general Python code with its built-in functions. Note though that this block is not intended to read simple tabular files, like the CSV format. In most cases, such files are easier to read and write using the CSVParser and CSVGenerator blocks.

Configuration Dialog

Usually a Text block is configured using a template file where you select values in the text and specify which variables to read or write.

../_images/page_blocks_Text_configure.png

The main pane 1 shows the template file contents. The template can be reloaded or opened in your default text editor using the toolbar buttons 2. If the input is an existing file on disk, this file is automatically shown as the template, and browsing for a template file is disabled. Loading a separate template 3 is needed, for example, when the input file received to a port (the block is used to parse program output).

Input and output files are configured on the respective panes 4 and 5. The b_browse buttons on these panes open the generic file configuration dialog — for details on these settings, see the File block page.

The Operations pane 6 shows the sequence of operations that the block will perform when running, such as reading or writing values in the file. Here you can edit the sequence and test it before running the workflow, using the commands available on the pane’s toolbar and in its menu.

The Variables pane 7 shows block variables, their names, types and test values. This pane allows to edit variables that were added from the template, as well as to add variables manually. Test values of variables shown here are used when you run operation tests.

Generate Program Input

When the Text block generates an input file for some program, it needs a sample of such a file. The output of the block is a file which contains parameters received from other blocks in the workflow, from workflow configuration in Run, or other sources.

../_images/page_blocks_Text_configure_input.png
  • Click b_browse in the Input file pane to open the file configuration dialog.
  • In the dialog, set file origin to project and browse for a file. Click b_ok in the dialog to return to block configuration.
  • The generated file is sent to the port named output by default. When you use Text to write parameters to a file, there is no need to change any settings on the Output file pane.
  • The file you selected as input is automatically used as the template 1. Note that the block assumes UTF-8 encoding by default; if your file uses another encoding, select it using the Text encoding option.
  • In the template, select the values you want to replace 2.
  • When you release the mouse button, a pop-up appears 3 that lets you create a new input variable or select an existing one.
  • Input a name or select the variable, then click the write button b_blconf_write in the pop-up.
  • Required operations 4 are added automatically. If you have input a new variable name, the block also creates this variable 5 and sets its properties.
  • The block automatically tests new operations. These tests can also be run manually — see Testing for details.
  • If parameter values are found in different parts of the template, repeat the above steps for other locations.

For more details on how selections work, see Quick Selection. Variables and operations can also be added manually — see sections Variables and Operations.

Parse Program Output

When the Text block parses output received from some program, its input file is received from the block that launches this program. Since this file appears only when the workflow runs, usually a separate template file (a sample of output) is used when configuring the block. The output of the block in this case are parameter values found in the input file.

../_images/page_blocks_Text_configure_output.png
  • The input file is accepted to the port named input by default. When you use Text to read parameters from a file, there is no need to change any settings on the Input file pane. The output file is not used in this case. By default, it is sent to the port named output; you can disable this in the Output file pane settings or leave them as is.
  • To load a template file, click b_browse in the Template file pane and navigate to the file. The template should be an example of the input file that is received when the workflow runs.
  • The Template file pane shows file contents 1. The block assumes UTF-8 encoding by default; if your file uses another encoding, select it using the Text encoding option. Note also that the template is actually never read at the workflow run-time — it is used only when configuring the block, in order to simplify adding variables and operations.
  • In the template, select the values to read from file 2.
  • When you release the mouse button, a pop-up appears 3 that lets you create a new output variable or select an existing one.
  • Input a name or select the variable, then click the read button b_blconf_read in the pop-up.
  • Required operations 4 are added automatically. If you have input a new variable name, the block also creates this variable 5 and sets its properties.
  • The block automatically tests new operations. These tests can also be run manually — see Testing for details.
  • If parameter values are found in different parts of the template, repeat the above steps for other locations.

For more details on how selections work, see Quick Selection. Variables and operations can also be added manually — see sections Variables and Operations.

Quick Selection

Quick selection is intended to simplify Text block configuration. It is not as flexible as manual editing of operations, but works in most cases when parameter values are located in a column, row, or other rectangular area in the template. The block automatically resolves your selections and adds operations that relocate the working frame and read or write data.

Note that a selection should include only the values to be replaced, not entire lines in the template — see the examples in Generate Program Input and Parse Program Output.

Typical examples of using quick selection:

  • A single value or word in the template is resolved to a scalar variable — for example, RealScalar or StringScalar.
  • A row or column of values is resolved to a vector variable by default. Such selections can also use List variables.
  • A table-like area with multiple rows and columns is resolved to a matrix variable. This works only if the “table” is rectangular (all rows and columns have the same number of values).

A selection may also include numeric values with column or row names (text labels). Such selections use Dict variables — associative arrays of (key, value) pairs, where keys have the same names as columns (rows).

Dict variables are useful if you have a big set of named values and want to avoid creating a specific variable for each value. Also, a Dict variable does not rely on the order of components, as vector or List variables do. The value under a key is usually a vector (corresponds to a row or column in the template). Scalars or single-element vectors can also be used to replace or read scalar values in the template.

For example:

../_images/page_blocks_Text_dict_selection1.png

This selection can be replaced with a Dict {"x1": 1.1, "x2": -0.9} (contains scalars) or {"x1": (1.1), "x2": (-0.9)} (contains single-element vectors).

Another example:

../_images/page_blocks_Text_dict_selection2.png

This selection can be replaced with a Dict {"x1": (1.1, 2.1), "x2": (1.2, 2.2), "x3": (1.3, 2.3)}.

Note

Dictionary replacements also work with named rows and columns of different lengths, but in such cases the block may be not able to resolve the selection automatically, so you will have to add operations manually.

Testing

The Text block can be tested before running the workflow, allowing to verify that operations are performed correctly. When you use quick selections, the block automatically tests new operations and shows results. Tests can also be run manually, using the buttons on the Operations pane toolbar:

  • b_blconf_test tests all operations in the list.
  • b_blconf_test_next tests the next untested operation only.
  • b_blconf_sweep clears test results: removes test values from the template and reverts all operations to untested state.

Note that before testing the Write value... and Insert value... operations, you should set test values for input variables. To add a test value, double-click the “Test value” field for a variable, or select Edit variable... from the Variables pane menu.

../_images/page_blocks_Text_test_passed.png

When you run tests, the test values 1 of input variables are shown highlighted 2 in the template (these changes are not saved to the template file). The Read value... operation gets values of output variables from the template and shows them in the “Test value” column on the Variables pane. More information on tested operations is available in the tooltips 3 on the Template file pane.

../_images/page_blocks_Text_test_failed.png

If a test fails, the unsuccessful operation is marked in the list 1 and in the template 2, and error details 3 are shown on the Template file pane.

Advanced

This section provides more details on properties of variables, operations settings, scripting, and file configuration.

Variables

The Text block allows to declare variables manually and configure properties of variables added by quick selections.

To add a variable, click b_blconf_add on the Variables pane. This button opens the Add variables dialog.

../_images/page_blocks_Text_addvar.png
  • Name: specifies the name of the variable. Names are case-sensitive; they should begin with a letter and contain only letters, numbers, and underscores. Multiple variables can be added at once using a comma-separated list of names. When you add multiple variables, all of them get the same properties; these properties can be edited afterwards.
  • Ports: selects which ports are created for the variable: input, output, or an input-output port pair. Port names are the same as the name of variable.
  • Type: selects the variable’s data type.
  • Test value: specifies the value that is written into the template when you test operations on the Operations pane. This setting is intended for input variables.

When you click b_add in this dialog, the variable appears on the Variables pane and corresponding ports are added to the block. After you add a variable, its properties can be edited either on the pane (hover a property and click the edit icon) or using the Edit variable... command from the pane’s menu.

Operations

Operations define how the block searches for data in the input file, reads and writes values. When you use quick selections, the block automatically configures the required sequence of operations and shows them on the Operations pane. You can edit the automatically added operations, add operations manually, and change their order.

  • To edit an operation, double-click it or select Edit operation... from the pane’s menu.
  • To add operations manually, use the Add operation sub-menu in the pane’s menu.
    • To insert an operation somewhere in the list, select an existing operation before adding a new one. The new operation will be added previous to the selected one.
    • To add an operation to the end of the list, deselect all operations first (click empty area on the Operations pane).
  • To reorder operations, simply drag them in the list.

Reading and writing values can be understood as a two-step process. The block first sets a working frame inside the file using the Set frame start... and Set frame end... operations that search for specific text strings. After the frame is set, line numeration begins from the frame start. The Write value..., Read value..., and Insert value... operations then use this line numeration to specify value locations. This method allows to work with values which locations in the file are not fixed.

Initially the working frame start and end are placed on the first and the last line of the file. In the case when a value in the file is always on the same line, you can skip operations that set the working frame and simply specify this line’s number in other operations’ settings.

If you change the working frame location more than once, note that Set frame start... always searches from the current frame start position, going downwards, and Set frame end... searches from the current frame end going upwards. In most cases you should use the Reset frame operation before each relocation of the working frame.

Set frame start...

Searches down from the current frame start position. Finds a line that matches the specified pattern and sets the working frame start to a new location.

../_images/page_blocks_Text_set_start.png
  • The search begins from the current working frame start, which is not always the first line of file.
  • The search goes down.
  • If you want to search from the beginning, use Reset frame first.

The pattern can be a text string (default) or a regular expression.

The search skips matched lines until the number of matches reaches the value specified in “Stop at N match”. By default, stops at the first occurrence.

After the search stops, the location can be additionally adjusted by moving a few lines up or down from the finally matched line.

Set frame end...

Searches up from the current frame end position. Finds a line that matches the specified pattern and sets the working frame end to a new location.

../_images/page_blocks_Text_set_end.png
  • The search begins from the current working frame end, which is not always the last line of file.
  • The search goes up from the current frame end.
  • If you want to search from the end of file (up from the last line), use Reset frame first.

The pattern can be a text string (default) or a regular expression.

The search skips matched lines until the number of matches reaches the value specified in “Stop at N match”. By default, stops at the first occurrence.

After the search stops, the location can be additionally adjusted by moving a few lines up or down from the finally matched line.

Reset frame

Reset working frame start and end positions to default (the first line of file and the end of file, respectively). This operation has no additional settings.

Write value...

Writes current value of the variable to the specified location within the working frame. Note that this operation is intended to replace existing values and cannot insert new lines — see Insert value... for this case.

../_images/page_blocks_Text_write_value.png
  • Variable: selects the variable to write. Alternatively, you can input a new name here to add the variable along with the operation.
  • Elements: intended for vector and matrix variables, allows to select specific components. For a matrix variable, components are rows. Note that component indexing starts from 0.
    • All: write all components.
    • Index: write one component — a single element from a vector, or a single row from a matrix.
    • Slice: allows to write a subset of variable’s data. This option uses the Python slice syntax (start:stop:step).
  • Lines: specifies lines to write within the working frame. Lines are numbered from the current frame start, and numbering starts from 0. Multiple lines can be specified as a list of numbers and ranges (n,m,k-l) or using the Python slice syntax (start:stop:step).
  • Delimiters: specifies strings interpreted as field separators in each line. By default, delimiter is any number of whitespace or tab characters. Other delimiters can be specified using the regular expression syntax.
    • Regex: delimiter character, string, or regular expression. Allows to specify multiple delimiters — for example, >|< can be useful when the file contains XML tags (| means “or” in regular expressions). Note that there are more characters that have special meaning in regular expressions: . \ + * ? ^ $ [ ] { } ( ) | /. To be interpreted literally, these characters have to be escaped with a backslash, for example \+.
  • Fields: specifies fields to write; fields are parts of the line separated by the delimiter. Similarly to lines, multiple fields can be specified as a list or a slice. To write all fields in a line, input :.
  • Format style: specifies number format to use when writing values.
    • No format: default, writes values using the default Python formatting.
    • C: allows to use C format specifiers, such as %.5f for a floating point value with a precision of 5.
    • Fortran: allows to use Fortran format specifiers, such as F10.3 to use 10 positions for a floating point value with a precision of 3.

Note that this operation writes the actual value of a block variable. Usually this value is received to the corresponding input port, however you can also set it by other means. For example, you can use the Read value... operation to set a variable and then write this variable to another location, or use the Python code... operation to assign a value manually.

Read value...

Reads data from the specified location within the working frame and assigns value to a variable.

../_images/page_blocks_Text_read_value.png
  • Variable: selects the variable to store the data. Alternatively, you can input a new name here to add the variable along with the operation.
  • Elements: intended for vector and matrix variables, allows to set their specific components. For a matrix variable, components are rows. Note that component indexing starts from 0.
    • All: the data fills all components of a variable.
    • Index: fill one component — set a single element of a vector, or a single row of a matrix.
    • Slice: select multiple components to fill. This option uses the Python slice syntax (start:stop:step).
  • Lines: specifies lines within the working frame to read from. Lines are numbered from the current frame start, and numbering starts from 0. Multiple lines can be specified as a list of numbers and ranges (n,m,k-l) or using the Python slice syntax (start:stop:step).
  • Delimiters: specifies strings interpreted as field separators in each line. By default, delimiter is any number of whitespace or tab characters. Other delimiters can be specified using the regular expression syntax.
    • Regex: delimiter character, string, or regular expression. Allows to specify multiple delimiters — for example, >|< can be useful when the file contains XML tags (| means “or” in regular expressions). Note that there are more characters that have special meaning in regular expressions: . \ + * ? ^ $ [ ] { } ( ) | /. To be interpreted literally, these characters have to be escaped with a backslash, for example \+.
  • Fields: specifies fields to read from; fields are parts of the line separated by the delimiter. Similarly to lines, multiple fields can be specified as a list or a slice. To read all fields from a line, input :.
  • Convert to: selects the data type of the variable. This option should be used when you input a new name in the dialog (create a new variable with the operation). If you have selected an existing variable, the correct data type is selected automatically.

Note that this operation only assigns a block variable; the value of variable is output only when the block finishes all operations. It is possible to change the value before output, collect data to a single variable using multiple reads (for example, to read different rows of a matrix variable), or use the stored value in the Write value... or Insert value... operations.

Insert value...

This operation can be understood as a special version of the Write value... operation. It can replace the entire working frame with data stored in a variable (removing all frame contents), or insert data above or below the working frame (adding new lines).

../_images/page_blocks_Text_insert_value.png
  • Placement: selects where to write the variable data. Writing above or below the working frame adds new lines as needed. Replacing the working frame means that all its contents will be removed and the variable data will be added instead.
  • Transpose vector and matrix values: transposes vectors and matrices before writing. When disabled: vector variable becomes a single line; matrix rows are lines. When enabled: vector variable becomes a column on multiple lines; matrix columns are lines.
  • Separate with: selects the field delimiter. You can select one of the default delimiters or specify your own.

Other settings are the same as for the Write value... operation.

Python code...

Allows to add Python code snippets to the sequence of operations. Selecting this operation from the menu opens the code editor.

../_images/page_blocks_Text_pycode.png

Snippets contain general Python code; you can import modules, define functions and classes, and so on (see Scripting for more details). Note that all snippets work in the same scope shared with other operations — in particular, block variables from the Variables pane are visible as global variables in the code.

Scripting

All operations in the Text block are in fact function calls in the block’s script. This script can also be edited directly, allowing to combine general Python code with block operations.

Selecting Edit script... from the Operations pane menu opens a window where you can view the script and make simple edits.

../_images/page_blocks_Text_edit_script.png

In the script, you can define functions and classes, import modules (see Available Modules), and so on. For long scripts it is better to use an external editor, then copy your code to the Edit script window.

Operations are called from the script using the methods of the template object which is a Template class instance. These methods provide replacements for a few most essential Python’s built-in methods of file objects, since you have no direct access to the template file from the script.

Names of input and output block variables are added to the script namespace as global variables. Your script can use other globals too — you are not required to declared every global as a block variable.

When the block starts, input variables in the script are automatically assigned values from corresponding input ports. For example, if you have an input port my_invar, print my_invar outputs the received value to console at the run-time. If you assign a value to an output variable, this value is sent to a corresponding output port when the block finishes.

Note that when port values are assigned to or read from script variables, they are converted between pSeven and Python data types. For example, a RealMatrix input variable becomes a 2D numpy.ndarray of floats in the script (see Typesystem and Conversion Rules for details).

Scripting in Text does not require you to install Python because the block uses pSeven’s in-built Python interpreter.

Template Class

class Template

Represents the template file. Template object, named template, is initialized in the script by the block. You should use methods of this existing object.

insert(value, place=INSERT_ABOVE, delimiter=' ', transpose=False, format_style=FORMAT_NO, format_string='')

Insert data values into the file.

Parameters:
  • value (float, int, str, bool, list, tuple, dict, numpy.ndarray) – the data to write
  • place (str) – insert placement
  • delimiter (str) – field delimiter
  • transpose (bool) – whether to transpose vectors and matrices before writing
  • format_style (str) – number format
  • format_string (str) – number format string

The value can be a script variable, not necessary a block variable with a corresponding port.

Placement can be:

  • INSERT_ABOVE: add new lines above the working frame.
  • INSERT_BELOW: add new lines below the working frame.
  • INSERT_INSTEAD: replace the working frame.

The delimiter is the string to use as a field separator, empty string means no separators.

Numeric values can be formatted with format_style (one of the following) and format_string:

  • FORMAT_NO: default Python formatting (%s), format_string is ignored.
  • FORMAT_C: C formatting.
  • FORMAT_FORTRAN: Fortran formatting.

In format_string, use standard format specifiers of the selected style.

See the Insert value... operation description for more details.

read(lines, fields, delimiter='', convert='RealScalar')

Read data from the file.

Parameters:
  • lines (str, int) – lines to read from
  • fields (str, int) – fields to read
  • delimiter (str) – field delimiter
  • convert (str) – data type of the variable
Returns:

data

Return type:

float, int, str, bool, list, tuple, dict, numpy.ndarray

The lines and fields arguments can specify a comma-separated list of numbers and ranges ("1, 3-5, 8") or a range as a Python slice ("2:9:2", "-3:") — note that both forms are str. Single line or field number may be int.

The delimiter is a regular expression. If the delimiter is an empty string, any number of whitespace characters is interpreted as a field separator.

Return type depends on the type of the variable set by convert (see Python to pSeven Types Conversion), which should be a string containing a pSeven typename — for example, "IntScalar" or "RealMatrix".

See the Read value... operation description for more details.

reset_frame()

Reset working frame start and end positions to default — the first line of file and the end of file, respectively.

set_frame_end(search, times=1, as_regex=False, shift=0)

Set location of the working frame end.

Parameters:
  • search (str) – search string
  • times (int) – how many times to repeat the search
  • as_regex (bool) – parse search as a regular expression
  • shift (int) – move shift lines down (up, if negative) after finally matching search

Search for a line that matches search, going up from the current end position, skipping matched lines until times matches are made, and finally applying shift.

See the Set frame end... operation description for more details.

set_frame_start(search, times=1, as_regex=False, shift=0)

Set location of the working frame start.

Parameters:
  • search (str) – search string
  • times (int) – how many times to repeat the search
  • as_regex (bool) – parse search as a regular expression
  • shift (int) – move shift lines down (up, if negative) after finally matching search

Search for a line that matches search, going down from the current begin position, skipping matched lines until times matches are made, and finally applying shift.

See the Set frame start... operation description for more details.

write(value, lines, fields, delimiter='', format_style=FORMAT_NO, format_string='')

Rewrite some data in the file.

Parameters:
  • value (float, int, str, bool, list, tuple, dict, numpy.ndarray) – the data to write
  • lines (str, int) – lines to write
  • fields (str, int) – fields to write
  • delimiter (str) – field delimiter
  • format_style (str) – number format
  • format_string (str) – number format string

The value can be a script variable, not necessary a block variable with a corresponding port.

The lines and fields arguments can specify a comma-separated list of numbers and ranges ("1, 3-5, 8") or a range as a Python slice ("2:9:2", "-3:") — note that both forms are str. Single line or field number may be int.

The delimiter is the string to use as a field separator, empty string means no separators.

Numeric values can be formatted with format_style (one of the following) and format_string:

  • FORMAT_NO: default Python formatting (%s), format_string is ignored.
  • FORMAT_C: C formatting.
  • FORMAT_FORTRAN: Fortran formatting.

In format_string, use standard format specifiers of the selected style.

See the Write value... operation description for more details.

Available Modules

pSeven’s Python distribution includes a number of useful modules which you can import in a script:

  • Scientific computing: numpy, pandas, scipy, sympy, scikit-learn, and networkx.
  • Plotting: bokeh and matplotlib with cycler.
  • Excel support: openpyxl, xlrd and xlwt (note that pSeven also provides the Excel integration block).
  • PyWin32 modules — see PyWin32 Documentation.
  • Markup and parsing: et_xmlfile, fortranformat, markupsafe, pyparsing, whoosh, and yaml.
  • Networking: paramiko, requests, and tornado with tornado_json.
  • Cryptography: Crypto (PyCrypto) and ecdsa.
  • Various utilities: astor, decorator, and six; psutil and lockfile; dateutil, jdcal, and pytz.

Note that this section lists only names of modules that can be imported in user scripts. The list does not include names of all additional packages installed in pSeven’s Python; if interested, you can find them in section Open Source Components.

Input and Output Files

The input and output files in Text can be configured in various ways — they use the generic file configuration component (detailed on the File block page). This section notes some useful configurations, in addition to the most common ones which were mentioned in sections Generate Program Input and Parse Program Output.

  • When Text is used to parse a file, this file is usually received to the input port (has port origin). However, you can also set up file exchange on disk: set input file origin to sandbox and configure the Text block sandbox so it points to this file’s directory. This configuration may be useful if the files to parse are created by an external process, or their source is a block that saves files to disk instead of sending them to ports. In the latter case, you can set both the source block’s sandbox and the Text block sandbox to the same directory, designating it as a file exchange location — see section Sandbox for details.

  • Default output configuration creates a new file of temporary origin which is sent sends it to the output port. Temporary files are not saved on disk when the workflow runs, but you can reconfigure the output to keep generated files.

    If the block generates only one output file on each workflow run, you can simply change output file origin to project and specify its path relative to the project directory. If the file with this name does not exist, it will be created by the block. Note that if it does exist, the block will overwrite its entire contents. Also, if the path includes a subdirectory, this subdirectory must exist when the workflow starts: the block does not create directories automatically. You can create a new project subdirectory in Workspace using the Project pane.

    If you change the file origin and leave the box in the Output Port pane checked, the block will both output the generated file to port and write it to disk. This is a clear solution if you save only one file, but it does not work if the Text is a part of a cycle, since it will write to the same file on each iteration and replace the previous results.


  • If the Text block works in a cycle and saves generated files to disk, every file should have a unique name so they do not overwrite each other. Possible solution is to leave output file settings default and send the generated file to a Program block — the same that launches an external program, or an additional one used only to save the file. The Program block can create a copy of the incoming file, giving it a name with a timestamp.

    For example, if Program accepts the generated temporary file to the my_infile input port, add a line like copy @{my_infile} X:\\destination\\path\\filename_@{timestamp}.txt (Windows) or cp @{my_infile} ~/destination/path/filename_@{timestamp}.txt (Linux) to the shell script. This saved copy of the file is not removed when pSeven deletes the original (temporary) file. Here, @{timestamp} is a date and time substitution available in the Program block by default.

    Note

    This solution can be combined with the Program sandbox setting to avoid using absolute destination paths. Use a relative sandbox path to place the sandbox directory inside your project (see section Sandbox for details). In the shell script in Program, remove destination path from the copy command, keeping the filename only. Thus file copies will be created in the sandbox directory you have configured, because it is the working directory for the block. For example, copy @{my_infile} filename_@{timestamp}.txt under Windows copies the received temporary file to YourProjectDir\SandboxDir\filename_timestamp.txt.

Options

Error handling behavior

The action to perform if the block encounters an error.

Value:stop workflow, output defaults and signal, output signal only
Default:stop workflow

Errors in the Text block can occur when it is unable to generate or parse a file. Often a file parse error in Text indicates that there was an error in the block that sent the file to Text — usually in this case Text receives an empty file where specified values cannot be found.

When this option is set to stop workflow, the Text block simply reports an error and the workflow interrupts.

If set to output defaults and signal, the block suppresses the error. Output ports in this case send values assigned to them (the defaults), and the done port outputs a False value (the signal). Note that port values are not the same as the test values of variables: port values are set on the Ports tab in the block configuration dialog.

The block automatically assigns values to output ports depending on their type (the corresponding variable’s type). Default output port values are:

  • NaN for RealScalar ports,
  • -1 for IntScalar ports,
  • an empty string "" for StringScalar ports,
  • False for BoolScalar ports,
  • zero-size vectors and matrices for vector and matrix ports,
  • an empty list [] for List ports, and
  • an empty dict {} for Dict ports.

The output signal only behavior means to output only the False value to done; nothing is output to other ports.

Text encoding

The encoding for the template, input and output files.

Value:name of the encoding
Default:utf8

New in version 6.10.

By default, the block reads template and input files as UTF-8 and encodes output in UTF-8 too. If your files use another encoding, you will have to specify it with this option in order to parse and generate files correctly. Selected encoding always applies to all files processed by the block.