FILEAPPEND stage

Purpose, Argument, Streams, Usage, Examples, Related

Syntax

                                         (2)┌─WRITE──┐ 
                    ┌─NOCLOse─┐             ├─R/W────┤
>>──┬─>>─────────┬──┼─────────┼──┬───────┬──┼────────┼──┬──────────┬─────────────────>< 
    └─FILEAPPend─┘  └─CLOse───┘  └─RECno─┘  ├─RDONLY─┤  └─filename─┘
                                            └─R/O────┘    (1)

Notes:
(1) The filename operand is only allowed if the stage does not have a secondary 
    input stream connected.
(2) Unless the WRITE keyword is specified; a file that is write-protected
    (RDONLY) remains write-protected after it has been processed.
(3) FILEAPPEND cannot be specified as the first stage in a pipeline.

Purpose

Use the FILEAPPEND stage to create a disk file or append to the contents of an existing disk file.

FILEAPPEND reads records from its primary input stream and writes them to the specified file and to its primary output stream, if it is connected. FILEAPPEND prepends a Line-Feed character to each output record that it writes to the specified file, primary output stream records are written unchanged. If the file already exists, FILEAPPEND appends the records.

If you do not specify a fully qualified path and file name, the FILEAPPEND stage will search for the input file in the current working directory, otherwise, it will create a new file in the current working directory.

Argument

NOCLOse
specifies that the output file is closed once a new output filename is encountered.
CLOse
specifies that the output file remains open until end-of-file is reached on the primary input stream.
RECno
specifies that a record number should be inserted in to both the output file record and the primary output stream record.
WRITE
R/W
specifies that the output file will be enabled for reading and writing. Note, that when FILEAPPEND writes to an existing, write-protected file; unless you specify the WRITE keyword, by default FILEAPPEND will save the file as write-protected.
RDONLY
R/O
specifies that the output file will be write protected. The file's arttibute will be set to read-only. Note, that when FILEAPPEND writes to an existing, write-protected file; unless you sepcify the WRITE keyword, by default FILEAPPEND will save the file as write-protected.
filename
is the name of the output file.

Streams

The following streams and files are used by the FILEAPPEND stage:

Input streams
- When the secondary input stream is connected
  
  FILEAPPEND will not allow the filename argument to be specified. FILEAPPEND first reads a record from its secondary input stream, which it treats as the name of the file to which it should write.
  - With the CLOse keyword; if the content of the record (the filename) is different from the previous secondary input stream record, FILEAPPEND closes the current output file and opens the new one specified in the record.
  - With the NOCLOse keyword (the default); if the content of the record (the filename ) is different from the previous secondary input stream record, FILEAPPEND first searches the file cache for an entry matching this new file and if one exists, FILEAPPEND simply switches its focus to this existing (already open) file. Otherwise, FILEAPPEND opens the new file and adds its details to the file cache.
  FILEAPPEND 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, if it is connected. This process continues until the end-of-file is reached on the primary input stream. At end-of-file; FILEAPPEND traverses the cache and closes all of the files.
  - Secondary input stream:
```
input:

|...+....1....+....2....+....3....+....4....
c:\myfile.dat
c:\myfile.dat
d:\yourfiles\yourfile.dat
..
..
d:\yourfiles\yourfile.dat
```
  - Primary input stream:
```
input:

|...+....1....+....2....+....3....+....4....
record
record
record
..
..
record
```
- When the secondary input stream is not connected, the filename argument is allowed
  1. When the filename argument is specified
    
    FILEAPPEND reads records from its primary input stream and writes them unchanged to the specified file, and to its primary output stream, if it is connected.
    
    Primary input stream:
```
input:

|...+....1....+....2....+....3....+....4....
record
record
record
..
..
record
```
  2. When the filename argument is not specified
    
    FILEAPPEND expects its primary input stream records to follow a specific format; the record must comprise an output filename, followed by the delimiter 0xff and the record (data) to write to the output file.
    
    FILEAPPEND extracts the output filename and if it differs from the filename specified in the previous primary input stream record (the current output file), and,
    - With the CLOSe keyword; if the content of the record (the filename) is different from the previous primary input stream record, FILEAPPEND closes the current output file and opens the new one specified in the record.
    - With the NOCLOse keyword (the default); if the content of the record (the filename) is different from the previous primary input stream record, FILEAPPEND first searches the file cache for an entry matching this new file and if one exists, FILEAPPEND simply switches its focus to this existing (already open) file. Otherwise, FILEAPPEND opens the new file and adds its details to the file cache.
    FILEAPPEND then writes the record (data) part of the primary input stream record to the specified file, and to the primary output stream, if it is connected.
    
    Primary input stream:
```
input:

|...+....1....+....2....+....3....+....4....
c:\myfile.datXrecord
c:\myfile.datXrecord
d:\yourfiles\yourfile.datXrecord
..
..
d:\yourfiles\yourfile.datXrecord
```
Output file
- Without the RECno keyword:
  
  FILEAPPEND writes the data part of the primary input stream record to the specified file.
```
output file:

...|...+....1....+....2....+....3....+....4....
   **** Top of file ****
 1 record
 2 record
 3 record
 . ..
 . ..
99 record
   **** End of file ****
```
- With the RECno keyword:
  
  FILEAPPEND writes the current output record number; a ten-digit field, right-aligned with leading spaces, the delimiter 0x20 (a blank) and the contents of the primary input stream record to the specified file.
```
output file:

...|...+....1....+....2....+....3....+....4....
   **** Top of file ****
 1          1Brecord
 2          2Brecord
 3          3Brecord
 .         ..
 .         ..
99         99Brecord
   **** End of file ****
```
Output streams
- Primary output stream:
  (without the RECno keyword)
  
  FILEAPPEND writes the data part of the primary input stream record to the specified file.
```
output:

|...+....1....+....2....+....3....+....4....
record
record
record
..
..
record
```
- Primary output stream:
  (with the RECno keyword)
  
  FILEAPPEND writes the current output record number; a ten-digit field, right-aligned with leading spaces, the delimiter 0x20 (a blank) and the contents of the primary input stream record to the specified file.
```
output:

|...+....1....+....2....+....3....+....4....
         1Brecord
         2Brecord
         3Brecord
        ..
        ..
        99Brecord
```

Usage

FILEAPPEND does not delay the records.
If FILEAPPOUT discovers that its primary input stream is not connected, the FILEAPPEND stage ends.
FILEAPPEND determines if an output file exists at the moment the file is opened for writing. FILEAPPEND opens an output file for writing when there is an output record to write. FILEAPPEND does not create empty files.
FILEAPPEND appends a Line-Feed character to all but the last record that it writes to the specified output file.
FILEAPPEND verifies that its secondary output stream is not connected and then begins execution.

Examples

The following pipeline reads records from the console and appends them to the file: myfile.txt. The pipeline ends when a null record is entered.
```
'pipe console | >> myfile.txt 
```

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

History

Version

Date

Action

Description

Pipelines

1.2

??.??.2025

changed

Application-wide rewrite

2.1

1.1

09.10.2007

added

Without the filename operand, each time FILEAPPEND reads an input record; it extracts the first word or quote (“) delimited phrase and uses this as the name of the target output file. The remainder of the input record data is used as the record which is written to the specified output file and to the primary output stream, if it is connected. If you do not specify a fully qualified path, FILEAPPEND creates or appends to the specified output file in the current working directory.

1.2

1.0

06.09.2007

created

First version.

1.0