FILEIN (<) stage v1.4

Pipelines v2.1

Purpose, Operands, Streams, Usage, Examples, Related

Home

Syntax

 ┌─ERRon─┐
>>──┬─FILEIN─┬──┼───────┼──┬─────────┬──┬───────┬──┬──────────┬──────────────────────><
 └─<──────┘ └─WARon─┘ └─REVerse─┘ └─RECno─┘ └─filename─┘
 (1)
 
Notes:
(1) The filename operand is only allowed if the stage is specified as the
 first stage in a pipeline.

Purpose

Use the FILEIN stage to read the contents of a disk file into a pipeline.

FILEIN reads the specified file; splitting its input at Line-Feed characters; discarding both individual and groups of Carriage-Return characters and writes the resulting records to its primary output stream.

Operands

●

ERRon

specifies that when FILEIN cannot open the input file (the file does not exist, for example) then an error is raised and FILEIN ends with an error exit code. This is the default.

●

WARon

specifies that when FILEIN cannot open the input file (the file does not exist, for example) then a warning is raised.

1.	When FILEIN is the first stage in a pipeline; the warning causes the stage to end, but with a successful exit code.
2.	When FILEIN is in any other position in a pipeline; the warning causes the input file to be skipped and FILEIN continues to read the next primary input stream record.

●

REVerse

specifies that the input file is read in reverse record order. That is to say; the last record of the file is written to the primary output stream first, followed by last-1, last-2 and so on until FILEIN reaches the physical start-of-file.

●

RECno

specifies that a record number should be inserted in to the primary output stream record.

●

filename

is the name of the file to read.

Streams

The following streams are used by the FILEIN stage:

●

When FILEIN is specified as the first stage in a pipeline.

FILEIN requires an input filename argument. FILEIN will read records from the specified file and for each line/record of the file, FILEIN writes an output record to its primary output stream.

●	Primary output stream: (without RECno operand) FILEIN writes a record that comprises the contents of the record read from the input file. |...+....1....+....2....+....3....+....4.... record record record .. .. record
●	Primary output stream: (with RECno operand) FILEIN writes a record that comprises a record number; a ten-digit field, right-aligned with leading spaces, the delimiter 0x20 (a blank) and the contents of the record read from the input file. |...+....1....+....2....+....3....+....4.... 1 record 2 record 1 record .. .. 99 record

●

When FILEIN is specified in any other position.

FILEIN will not allow the filename argument to be specified. FILEIN considers each record read from its primary input stream to contain the name of a file to open and read. Each time an input stream record is read that differs from the previous record, FILEIN closes the current input file and opens and begins reading the new input file; as specified by the input stream record. In this position, FILEIN behaves differently depending on whether or not its secondary output stream is connected.

1.

When the secondary output stream is connected.

●	Secondary output stream: FILEIN writes a record to the secondary output stream that contains the full directory path and filename of the input file. |...+....1....+....2....+....3....+....4.... c:\myfile.dat c:\myfile.dat d:\yourfiles\yourfile.dat .. .. d:\yourfiles\yourfile.dat
●	Primary output stream: (without RECno operand) FILEIN writes a record that comprises the contents of the record read from the input file. |...+....1....+....2....+....3....+....4.... record record record .. .. record
●	Primary output stream: (with RECno operand) FILEIN writes a record that comprises a record number; a ten-digit field, right-aligned with leading spaces, the delimiter 0x20 (blank) and the contents of the record read from the input file. |...+....1....+....2....+....3....+....4.... 1 record 2 record 1 record .. .. 99 record

2.

When the secondary output stream is not connected.

●

Primary output stream: (without RECno operand) FILEIN writes a record to the primary output stream that comprises; the full directory path and filename of the input file, the delimiter 0xff and the contents of the record read the input file. |...+....1....+....2....+....3....+....4.... c:\myfile.datXrecord c:\myfile.datXrecord d:\yourfiles\yourfile.datXrecord .. .. d:\yourfiles\yourfile.datXrecord

●

Primary output stream: (with RECno operand) FILEIN writes a record to the primary output stream that comprises; the full directory path and filename of the input file, the delimiter 0xff, a record number; a ten-digit field, right-aligned with leading spaces, the delimiter 0xff and the contents of the record read the input file. |...+....1....+....2....+....3....+....4.... c:\myfile.datX 1Xrecord c:\myfile.datX 2Xrecord d:\yourfiles\yourfile.datX 1Xrecord .. .. d:\yourfiles\yourfile.datX 99Xrecord

Usage

1.	The FILEIN stage does not delay the records.
2.	If FILEIN discovers that its primary output stream is not connected, the FILEIN stage ends.
3.	FILEIN splits its input at Line-Feed characters; discarding both individual and groups of Carriage-Return characters and writes the resulting records to its primary output stream.
4.	FILEIN verifies that an input file exist as when it is opened for reading (the file need only exist at runtime - at the moment FILEIN opens it), as such; FILEIN will not raise a potential file warning or error if another stage in the pipeline raises a runtime error before the FILEIN stage opens the file.
6.	FILEIN verifies that its secondary input stream is not connected and then begins execution.

Examples

1.	The following pipeline reads the file: myfile.txt and displays only the third word of each record on the console. 'pipe < myfile.txt | specs w3 1 | console'
2.	The example shows a pipeline which reads and input file in reverse record order. This option may be of particular use when reading a large file, where the records that are to be inspected lie at the end of the file. For example, a running active log-type file. Reading a file backwards
3.	This example shoes a pipeline that reads a list of files generated by the FILELIST stage command. Reading multiple files

Related

CONSOLE, FILEAPPEND (>>), FILEOUT (>), IN, OUT

History

Version	Date	Action	Description	Pipelines
1.4	??.??.2025	changed	Application-wide rewrite.	2.1
1.3	23.05.2011	changed	When FILEIN is specified in position where it is not the first stage in the pipeline and the file does not exist or cannot be opened due to an error, the < stage now issues a warning message (instead of an error message) and continues to process its input records.	1.9
1.2	22.04.2008	changed	FILEIN now splits its input at Line-Feed characters; discarding both individual and groups of Carriage-Return characters and writes the resulting records to its primary output stream.	1.5
		added	The REVERSE operand; which specifies that the input file is read in reverse record order.
1.1	09.10.2007	added	Deny write access to an open input file; this prevents the FILEOUT (>) and FILEAPPEND (>>) stages' and other external applications from altering the file while it is being read.	1.2
1.0	06.09.2007	created	First version.	1.0