- Group: 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.
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 the common Configure file dialog. This dialog is also used by other blocks that process files during the workflow run-time — load them from disk on start, receive or send through ports. Default file initialization settings can be different depending on the block, and usually there is no need to change them manually.
Configuring a File block consists of selecting how the file is initialized, specifying initial data to write (optional), and configuring the output.
Selected on the File origin pane. Other file settings depend on the origin you select.
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.
Used to read or write files located inside the project directory. By default, the file is not initialized and the path field is empty.
- File path — may be absolute or relative. Relative path is resolved as a path in the project directory. If you click and select a file in the project, the block automatically transforms its path to relative on or . To clear the path, click the icon.
- 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.
Used to read or write files in the block’s working directory, the sandbox (see Sandbox).
- File path — may be absolute or relative. Relative path is resolved as a path in the block sandbox directory. Note that if you click 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.
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.
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, Text block.
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).
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.
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 clickor 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 and browse to a file.
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.
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 on the Initial data pane. In 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 Configure file dialog, the initial data port may be 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.
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.
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 you load a file (via the Configure file dialog) which is used only by the block you configure — such as the template file in the Text block.