|
< (FILEIN) stage v1.3 |
Pipelines v2.0 |
|
Purpose, Operands, Streams used, Usage notes, Examples, See also |
|
Syntax |
>>__ _<______ __ _________ __ __________ ______________________________________________>< |_FILEIN_| |_REVerse_| |_filename_| (1) Notes:(1) The filename operand is only allowed if the stage is specified in a position where its primary input stream is not connected.
|
Purpose |
Use the < stage to read the
contents of a disk file into a pipeline.
< 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. The < stage may be specified in any position
where its primary output stream is connected.
|
● |
When < is specified in a position
where it does not have its primary input stream connected; < requires an
input filename argument. < will
read records from the specified file and for each line/record of the file,
< writes an output record to its primary output stream. |
||||
|
● |
When < is specified in a
position where its primary input stream is connected; < considers each
record read from its primary input stream to be the name of a file to open
and read. Each time an input stream record is read that differs from the previous
record, < closes the current input file and opens and begins reading the
new input file; as specified by the input stream record. In this position,
< behaves differently depending on whether or not its secondary output
stream is connected. |
||||
|
|
|
When specified in this position,
< will not allow the filename
operand to be specified.
|
Operands |
|
● |
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 < reaches the physical start-of-file. |
|
● |
filename is the name
of the file to read. |
|
Streams used |
The following streams are used by the < stage:
|
Stream |
Action |
|
|
|
|
Primary input stream |
< considers each record read from
its primary input stream to be the name of a file to open and read. < reads
from its primary input stream until it reaches end-of-file. |
|
Primary output stream |
< writes input file records to its primary output
stream. |
|
Secondary output stream |
<
writes the name of the file that it is currently reading to its secondary
output stream. |
|
Usage notes |
|
1) |
The < stage does not delay the records. |
|
2) |
If < discovers that its
primary output stream is not connected, the < stage ends. |
|
3) |
When < is the first stage in a pipeline and the file
you specify does not exists or cannot be opened due to an error, the < stage
will issue an error message and then terminate. However, when the < stage
is specified in any other position in a pipeline and the file does not exist
or cannot be opened due to an error, the < stage issues a warning message
and continues to process its input records. A BUFFER stage can be
used to prevent a pipeline from stalling. See: pipeline stalls for an explanation. |
|
4) |
< is designed to allow its secondary output stream to
be connected to the secondary input stream of the > (FILEOUT) stage; as in
the following example: **** Top of file ****01 Address Rxpipe0203 ‘pipe (endchar ?)’,04 ‘filelist noh drv=c subdir ext=txt’, 05 ‘| specs w5-* 1’,06 ‘| a: <’,07 ‘| specs w2-* 1’,08 ‘| xlate’,09 ‘| b: >’,10 ‘?’,11 ‘a:’,12 ‘| take *’,13 ‘| b:’1415 Exit 0**** End of file ****
The pipeline above traverses all
the directories of drive: C and reads each .txt file and converts the
contents to uppercase. The < stage feeds the name of each file it
processes to the secondary input stream of the > stage, which simply files
back the updated file. Note. This is only an example and should not be run;
Pipelines does not issue “are you sure?”
messages! With this pipeline configuration
you can only translate records, you cannot delete records or re-order them.
Ie) you should not use any stage which will alter the number or order of the
records, for example, you should not use stages such as; LOCATE, SORT or TAKE
etc.. If you do, the resulting files will be corrupted. |
|
5) |
If you need to process multiple files;
where records may be discarded or their output sequence altered, See. Processing multiple files
which explains how to do this. |
|
6) |
< 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. |
|
7) |
< validates the existence of
an input file at runtime, as such; < will not raise a missing file error
if another stage raises a runtime error before the < stage reaches this
validation point. |
|
8) |
< verifies that its secondary
input stream is not connected and then begins execution. |
|
Examples |
The following pipeline reads the
file: myfile.txt and displays only
the third word of each record on the console.
**** Top of file ****01 Address Rxpipe0203 ‘pipe < myfile.txt | specs w3 1 | console’
0405 Exit 0**** End of file ****