Purpose, Argument, Streams, Usage, Examples, Related

                ┌─ERRor─┐
>>──┬─<──────┬──┼───────┼──┬─────────┬──┬───────┬──┬──────────┬──────────────────────>< 
    └─FILEIN─┘  └─WARn──┘  └─REVerse─┘  └─RECno─┘  └─filename─┘
                                                     (1)

Notes:
(1) The filename operand is only allowed if the stage is specified as the
    first stage in a pipeline.

Use the FILEOUT stage to create a disk file or replace the contents of a disk file.

FILEOUT reads records from its primary input stream and writes them to the specified file and to its primary output stream, if it is connected. FILEOUT 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; FILEOUT creates a new file containing the records read from its primary input stream. If the specified file already exists, FILEOUT replaces the contents of the file with the records read from its primary input stream.

If you do not specify a fully qualified path and filename; the FILEOUT stage will create a new file in the current working directory.

• ERRor
  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.
  
  
• WARn
  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.
  

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 the RECno keyword)
    
    FILEIN writes a record that comprises the contents of the record read from the input file.
    
    

    output:
    
    |...+....1....+....2....+....3....+....4....
    record
    record
    record
    ..
    ..
    record
    

    
    
  • Primary output stream:
    (with the RECno keyword)
    
    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.
    
    

    output:
    
    |...+....1....+....2....+....3....+....4....
             1Brecord
             2Brecord
             1Brecord
            ..
            ..
            99Brecord
    

    
    
• 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.
       
       

       output:
       
       |...+....1....+....2....+....3....+....4....
       c:\myfile.dat
       c:\myfile.dat
       d:\yourfiles\yourfile.dat
       ..
       ..
       d:\yourfiles\yourfile.dat
       

       
       
     • Primary output stream:
       (without the RECno keyword)
       
       FILEIN writes a record that comprises the contents of the record read from the input file.
       
       

       output:
       
       |...+....1....+....2....+....3....+....4....
       record
       record
       record
       ..
       ..
       record
       

       
       
     • Primary output stream:
       (with the RECno keyword)
       
       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.
       
       

       output:
       
       |...+....1....+....2....+....3....+....4....
                1Brecord
                2Brecord
                1Brecord
               ..
               ..
               99Brecord
       

       
       
  2. When the secondary output stream is not connected
     
     
     • Primary output stream:
       (without the RECno keyword)
       
       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 from the input file.
       
       

       output:
       
       |...+....1....+....2....+....3....+....4....
       c:\myfile.datXrecord
       c:\myfile.datXrecord
       d:\yourfiles\yourfile.datXrecord
       ..
       ..
       d:\yourfiles\yourfile.datXrecord
       

       
       
     • Primary output stream:
       (without the RECno keyword)
       
       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 from the input file.
       
       

       output:
       
       |...+....1....+....2....+....3....+....4....
       c:\myfile.datX         1Xrecord
       c:\myfile.datX         2Xrecord
       d:\yourfiles\yourfile.datX         1Xrecord
                                         ..
                                         ..
       d:\yourfiles\yourfile.datX        99Xrecord
       

1. FILEIN does not delay the records.
   
   
2. If FILEIN discovers that its primary output stream is not connected, the FILEIN stage ends.
   
   
3. When the FILEIN stage opens an input file to read; FILEIN sets a lock on the file; the file cannot be opened by the FILEAPPEND stage or another FILEIN stage until the file is closed and the lock released.
   
   
4. FILEIN determines if an input file exists at the moment the file is opened for reading.
   
   
5. FILEIN splits its input records at Line-Feed characters; discarding both individual and groups of Carriage-Return characters and writes the resulting records to its primary output stream.
   
   
6. FILEIN verifies that its secondary input stream is not connected and then begins execution.

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. This example shows a pipeline which reads an 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 shows a pipeline that reads a list of files generated by the FILELIST stage command.
   
   Reading multiple files

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