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