TABLE OF CONTENTS

1. source/util/tools/logfile
2. source/util/tools/create_logfile
3. source/util/tools/write_logfile
4. source/util/tools/break_logfile
5. source/util/tools/tstamp_logfile
6. source/util/tools/open_logfile
7. source/util/tools/close_logfile

source/util/tools/logfile

   logfile - maintain a logfile 

   Log file maintenance routines.  These routines enable a
   program to open and close a log file, write time or date
   stamps to the file, and write arbitrary messages to the file.
   The file is kept closed and is only opened for appending
   when information is to be written, avoiding problems with
   unflushed buffers.  For this reason, logfile routines should
   not be called within time-sensitive loops, as the routines
   will generate system calls.

  Provides:    create_logfile (name, parmfile, restart, masterpe)
                       Creates the named log file and writes some header
                      information to it, including the build stamp and
                      the values of all runtime parameters in the global
                      parameter context.  The name of the parameter file
                      is taken as an input; it is echoed to the log file.
                      If restart is true, the file is opened in append
                      mode.  Only the master processor actually writes
                      anything.
              open_logfile()
                      Open the log file for writing, creating it first if
                      necessary.  open_logfile() and close_logfile()
                      should only be used if it is necessary to write
                      something directly to the log file unit with some
                      external routine.
              close_logfile()
                      Close the log file.
              stamp_logfile (string)
                      Write a date stamp and a specified string to the
                      log file.
              tstamp_logfile (n, t, dt)
                      Write a dated timestep stamp for step n, time t,
                      timestep dt to the log file.  n must be an integer,
                      while t and dt must be reals.
              write_logfile (string)
                      Write a string to the log file without a date stamp.
              break_logfile(char)
                      Write a 'break' (a row of char's) to the log file.

                get_perfmon_summary(n_intervals)
                        Called from end_flash, this subroutine calls

   runtime_parameters 

source/util/tools/create_logfile

     create_logfile
 

     create_logfile (name, parmfile, restart, masterpe)
     create_logfile (character (len=*), character (len=*), logical, integer)

     Creates the named log file and writes some header
     information to it, including the build stamp and
     the values of all runtime parameters in the global
     parameter context.  The name of the parameter file
     is taken as an input; it is echoed to the log file.
     If restart is true, the file is opened in append
     mode.  Only the master processor actually writes
     anything.

     name        name of logfile
     parmfile    name of parameter file being used
     restart     logical flag -- are we restarting an old run?
     masterpe    which MPI task should actually do the writing

   run_comment     comment to go at start of logfile
   run_number      number to print out in log file

source/util/tools/write_logfile

   write_logfile - write to the logfile

   write_logfile(string)
   write_logfile(character (len=*))

   Write a string to the log file.

   string    a string to write out 

source/util/tools/break_logfile

   break_logfile - write to the logfile

   break_logfile(char)
   break_logfile(character(len=1))

   Write a `break' (row of character char) into the log file.

source/util/tools/tstamp_logfile

   tstamp_logfile - stamp the logfile with a time and a timestep

   tstamp_logfile(n, t, dt)
   tstamp_logfile(integer, real, real)

   Write a timestep stamp to the log file.  A timestep stamp is
   a dated stamp containing the step number, simulation time,
   and timestep.

   n          timestep number
   dt         current size of timestep
   t          current simulation time

source/util/tools/open_logfile

   open_logfile - open the logfile for writing.

   open_logfile()

   Open the log file, either in append mode if it already exists
   or as a new file with a default name.

source/util/tools/close_logfile

   close_logfile - close the logfile

   close_logfile()

   Close the log file.