The `next file' Statement
=========================

   The `next file' statement is similar to the `next' statement.
However, instead of abandoning processing of the current record, the
`next file' statement instructs `awk' to stop processing the current
data file.

   Upon execution of the `next file' statement, `FILENAME' is updated
to the name of the next data file listed on the command line, `FNR' is
reset to 1, and processing starts over with the first rule in the
progam.  See Built-in Variables.

   If the `next file' statement causes the end of the input to be
reached, then the code in the `END' rules, if any, will be executed.
See `BEGIN' and `END' Special Patterns: BEGIN/END.

   The `next file' statement is a `gawk' extension; it is not
(currently) available in any other `awk' implementation.  You can
simulate its behavior by creating a library file named `nextfile.awk',
with the following contents.  (This sample program uses user-defined
functions, a feature that has not been presented yet.  
See User-defined Functions: User-defined, for more information.)

     # nextfile --- function to skip remaining records in current file
     
     # this should be read in before the "main" awk program
     
     function nextfile() { _abandon_ = FILENAME; next }
     
     _abandon_ == FILENAME && FNR > 1   { next }
     _abandon_ == FILENAME && FNR == 1  { _abandon_ = "" }

   The `nextfile' function simply sets a "private" variable(1) to the
name of the current data file, and then retrieves the next record.
Since this file is read before the main `awk' program, the rules that
follows the function definition will be executed before the rules in
the main program.  The first rule continues to skip records as long as
the name of the input file has not changed, and this is not the first
record in the file.  This rule is sufficient most of the time.  But
what if the *same* data file is named twice in a row on the command
line?  This rule would not process the data file the second time.  The
second rule catches this case: If the data file name is what was being
skipped, but `FNR' is 1, then this is the second time the file is being
processed, and it should not be skipped.

   The `next file' statement would be useful if you have many data
files to process, and due to the nature of the data, you expect that you
would not want to process every record in the file.  In order to move
on to the next data file, you would have to continue scanning the
unwanted records (as described above).  The `next file' statement
accomplishes this much more efficiently.

   ---------- Footnotes ----------

   (1)  Since all variables in `awk' are global, this program uses the
common practice of prefixing the variable name with an underscore.  In
fact, it also suffixes the variable name with an underscore, as extra
insurance against using a variable name that might be used in some
other library file.