|
> (FILEOUT) stage v1.0 |
Pipelines v1.9 |
|
Purpose, Operands, Streams used, Usage notes, Examples, See also |
|
Syntax |
>>__ _>_______ __ __________ __________________________________________________________><
|_FILEOUT_| |_filename_| (1) Notes: (1) The filename operand is only allowed if the stage does not have a secondary input stream connected.
|
Purpose |
Use the >
stage to create a disk file or replace the contents of a disk file.
> reads
records from its primary input stream and writes them to the specified file and
to its primary output stream, if it is connected. > appends a Line-Feed character
to each output record that it writes to the specified file, primary output
stream records are written unchanged. If the specified file does not already
exist; > creates a new file containing the records read from its primary
input stream. If the specified file already exists, >
replaces the contents of the file with the records read from its primary input
stream.
When >
replaces a file, it writes the records to a temporary work file and after the
work file has been successfully written to disk, the target file is erased and
the work file is renamed to the specified target filename. If its primary output stream is connected, > copies
each output record to its primary output stream. > cannot be specified as
the first stage in a pipeline.
When > has a
secondary input stream connected, the target filename argument is not allowed. The > stage first reads a
record from its secondary input stream, which it treats as the name of the file
to which it should write. If the content of the record is different from the
previous secondary input stream record, > closes the current output file and
opens the new one specified in the record. > next reads a record from its
primary input stream, writes this record to the target output file and then
writes the record to its primary output stream. This process continues until
the end-of-file is reached on the primary input stream.
If you do not
specify a fully qualified target filename,
the > stage will create a new file in the current working directory.
|
Operands |
|
Streams used |
The following streams are used by the >
stage:
|
Stream
|
Action |
|
|
|
|
Primary input
stream |
> reads records from its primary input
stream. |
|
Secondary input
stream |
> reads records from its secondary input stream, treating the
contents of each record as the name of the output file |
|
Primary output
stream |
> copies its primary input stream records to its primary
output stream. |
|
Usage notes |
|
1) |
> does not delay the records. |
|
2) |
When the > stage opens an output file,
the file remains locked against read and write access until the stage ends. |
|
3) |
If the output file
you specify already exists and the > stage does not receive any records to
process, the existing file remains unchanged. An existing file is never
replaced by an empty file. Also, if the pipeline is terminated with a CTRL-C
before the > stage has completed its processing, an existing file remains
unchanged. |
|
4) |
When > has its
secondary input stream connected, each time it reads a record from its
secondary input stream, > compares the contents of the previous record
with the contents of the current record, and if they are different, >
closes the current output file and opens a new one with the name specified in
the current secondary input stream record. |
|
5) |
The > stage is
designed to allow its secondary input stream to be connected to the secondary
output stream of the < (FILEIN) stage. As in the following example: pipe (endchar ?) filelist noh drv=c subdir ext=txt | specs w5-* 1 | a: <| specs w2-* 1 | translate upper | b: > ? a: | take * | b:
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. |
|
6) |
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. |
|
7) |
The > stage
appends a line feed character to all but the last record that it writes to
the specified output file. |
|
8) |
The > stage
verifies that its secondary output stream is not connected and then begins
execution. |
|
Examples |
The following
pipeline reads records from the console and writes them to the file: myfile.txt.
C:\>pipe ”console | > myfile.txt”