File

Tag: General

The File block is intended for advanced file management. It can create file objects, read files, or receive a file object and write it to disk.

Introduction

A file object in pSeven is a variable of the File type, which can be sent from or received to a port.

The File block uses a generic file configuration component which is also built into other blocks that load files from disk, receive or send them through ports. The difference is that the File block has no default initialization settings, while other blocks predefine their files — so usually there is no need to configure them manually. Yet if you do so, the configuration options are the same as if you were editing a File block.

Configuring a File block consists of selecting how the file is initialized, specifying initial data to write (optional), and configuring the output.

File Origin

Selected on the File Origin pane. File origin specifies certain file initialization settings. After selecting origin, the pane shows additional settings (for example, the file path).

Files of project or sandbox origin are files on disk. The difference between them is in how the block resolves relative file paths. For project file, the path is relative to the project directory. For sandbox file, the path is relative to the block’s sandbox directory.

Temporary files exist in memory only and have no path.

The block may also receive a file object from port instead of creating a new one.

None

The file is not initialized. Default for File blocks. Initial data can still be loaded to block memory, but the block does not write it to a file.

Project

Used to read or write files located inside the project directory.

Additional settings:

  • File path — may be absolute or relative. Relative path is resolved as a path in the project directory. If you click b_browse and select a file in the project, the block automatically transforms its path to relative on b_apply or b_ok.
  • Path from port — instead of typing a path or browsing for a file, you may set the block to accept the path as a StringScalar variable to a port with a predefined name. This port appears only when you check the box; the name is seen in the configuration dialog. If the received string contains a relative path, the resolution rule above also applies (the file is located in project directory).

This origin is intended for files in portable projects that can be moved to another location. It means that all input files have to reside in the project directory, and blocks have to use project files with relative paths.

Sandbox

Used to read or write files in the block’s working directory, the sandbox (see Sandbox).

Additional settings:

  • File path — may be absolute or relative. Relative path is resolved as a path in the block sandbox directory. Note that if you click b_browse and browse for a file in sandbox, the block does not transform its path to relative automatically.
  • Path from port — similar to this setting for the project origin. Relative path resolution rule applies (if the path received is relative, the file is located in the sandbox).

For sandbox files, relative paths are resolved each time the file object is accessed by any block. It means that, for example, if you create a sandbox file with a relative path in block A and send it to the block B which saves the file to disk, the file is saved in the sandbox for the block B, not A.

Temporary

Use temporary origin when you need a data file, but do not need to save it or load from disk. It creates a new memory object that acts as a file, but exists only while the workflow is running. Every temporary file has a unique identifier which is generated automatically.

This setting is default for blocks that output files to ports — for example, ApproxBuilder or the Text block.

Port

Use port origin when the block has to receive a file to port instead of creating a new one or loading it from disk. The port name is predefined and you can see it in the configuration window. The port itself is not present until you select this origin and apply settings.

Note that the true origin of the received file (project, sandbox, or temporary) will already be set, and this origin will not be changed.

This setting is default for blocks with input file ports — for example, ApproxPlayer or the Text block.

Initial Data

Configured on the Initial Data pane. The block can write arbitrary data to the file right after its initialization. The data can be loaded from another file or received to port. After selecting data source, the pane shows additional settings (write mode, for example).

None

Do not write anything. If you create a new file, it will be empty. If you open an existing file, its contents will be left unchanged.

From File

Initial data is loaded from a file and saved by the block. The block will store a copy of data (the file contents). Once you click b_apply or b_ok in block configuration dialog, this data is safe even if the original file gets moved or deleted: it is now saved with the workflow.

Path field is read-only. To load data, click b_browse and browse to a file.

Warning

If you select an existing file when setting the file origin, and also load initial data to the block, the file contents on disk will be changed when the block starts.

If you create a new file (type path to a file that does not exist), the initial data will become its initial contents. If you open an existing file, by default the initial data will overwrite everything in the file when the block starts (that is, the overwrite occurs when starting the workflow, not while configuring the block). This behavior may be changed to append (writes initial data to the end of file) using the corresponding checkbox in the Initial Data pane.

From Port

In this mode, the block accepts a file with the initial data to a port. The port name is predefined and you can see it in the Initial Data pane. On the File block this port is not present by default and appears only after you apply the initial data configuration. In other blocks that use the same file configuration component, the initial data port may pre-configured.

Note that the port for initial data is of File type, so it will not accept raw data such as RealMatrix and other types. The file object thus has to be created by another file-capable block. This mode is intended for complex workflows where you actually need to create run-time file objects copying the contents of another file but not its type.

Warning

If you select an existing file when setting the file origin, and configure the block to receive initial data to port, the file contents on disk will be changed when the block starts.

Write mode is similar to the case when initial data is loaded from a file.

Output Port

On the Output Port pane you can select whether to output the file to a port. The port name is predefined, but the port itself is not present until you check the box and apply settings. Note that in the File block configuration it is not checked by default.

The unchecked state is also default when the file component (built-in) loads a file which is used only by the block you configure — such as the template file in the Text block.