INTERFACE / PUBLIC COMPONENTS / NAMELIST / FILES / REFERENCES / ERRORS / BUGS / PLANS / PRIVATE COMPONENTS

MODULE utilities_mod

Contact: Jeff Anderson
Reviewers:  
Revision: $Revision: 1.4 $
Release Name: $Name: $
Change Date: $Date: 2005/10/17 19:48:47 $
Change history: see CVS log

OVERVIEW

Provides a number of tools used by most DART modules including tools for file IO, diagnostic tools for registering modules and recording namelist arguments, and and error handler.




OTHER MODULES USED

types_mod



PUBLIC INTERFACE

use utilities, only : file_exist
 get_unit
 check_nml_error
 open_file
 timestamp
 close_file
 register_module
 error_handler
 logfileunit
 initialize_utilities
 finalize_utilities
 dump_unit_attributes
 find_namelist_in_file
 check_namelist_read
 E_DBG, DEBUG
 E_MSG, MESSAGE
 E_WARN, WARNING
 E_ERR, FATAL

NOTES

Optional namelist interface &utilities_nml may be read from file input.nml.




PUBLIC COMPONENTS



var = file_exist(file_name)
 logical                      :: file_exist
 character(len=*), intent(in) :: file_name
 

Description

Returns true if file_name exists in the working directory, else false.

file_exist    True if file_name exists in working directory.
file_name    Name of file to look for.


var = get_unit()
 integer :: get_unit
 

Description

Returns an unused unit number for IO.

get_unit    An unused unit number.


var = check_nml_error(iostat, nml_name)
 integer                      :: check_nml_error
 integer, intent(in)          :: iostat
 character(len=*), intent(in) :: nml_name
 

Description

Given the iostat variable from a namelist read and the name of the namelist, makes sure that the iostat is an acceptable value. If not, generates a call to the error handler.

check_nml_error    Returned error code (same as iostat input).
iostat    Input error code from a namelist read.
nml_name    Name of the namelist that was read.


var = open_file(fname [, form, action])
 integer                                :: open_file
 character(len=*), intent(in)           :: fname
 character(len=*), optional, intent(in) :: form
 character(len=*), optional, intent(in) :: action
 

Description

Returns a unit number that is opened to the file fname. If form is not present or if form is "formatted" or "FORMATTED", file is opened for formatted IO. Otherwise, it is unformatted. The action string is the standard action string for Fortran IO (see F90 language description).

open_file    Unit number opened to file fname.
fname    Name of file to be opened.
form    Format: 'formatted' or 'FORMATTED' give formatted, anything else is unformatted. Default is formatted.
action    Standard fortran string description of requested file open action.


call timestamp([string1, string2, string3,]  pos)
 character(len=*), optional, intent(in) :: string1
 character(len=*), optional, intent(in) :: string2
 character(len=*), optional, intent(in) :: string3
 character(len=*), intent(in)           :: pos
 

Description

Prints the message 'Time is YYYY MM DD HH MM SS' to the logfile along with three optional message strings. If the pos argument is 'end', the message printed is 'Finished... at YYYY MM DD HH MM SS' and the logfile is closed.

string1    An optional message to be printed.
string2    An optional message to be printed.
string3    An optional message to be printed.
pos    If 'end' terminates log_file output.


call close_file(iunit)
 integer, intent(in) :: iunit
 

Description

Closes the given unit number. If the unit is not open, nothing happens.

iunit    File unit to be closed.


call register_module(src,rev,rdate)
 character(len=*), intent(in) :: src
 character(len=*), intent(in) :: rev
 character(len=*), intent(in) :: rdate
 

Description

Writes the source name, revision number and revision date to both the logfileunit and to standard out. All dart modules are supposed to register when first called.

src    CVS source file name.
rev    Revision number of source.
rdate    Date of revision.


call error_handler(level, routine, text, src, rev, rdate [, aut])
 integer, intent(in)                    :: level
 character(len=*), intent(in)           :: routine
 character(len=*), intent(in)           :: text
 character(len=*), intent(in)           :: src
 character(len=*), intent(in)           :: rev
 character(len=*), intent(in)           :: rdate
 character(len=*), optional, intent(in) :: aut
 

Description

Prints an error message to standard out and to the logfileunit. The message contains the routine name, an error message, the CVS source file, revision and revision date, and optionally the author. The level of severity is message, debug, warning, or error. If the level is greater than or equal to the TERMLEVEL (set in the namelist), execution is terminated. The default TERMLEVEL only stops for ERRORS.

level    Error severity (message, debug, warning, error). See below for specific ations.
routine    Name of routine generating error.
text    Error message.
src    Source file containing routine generating message.
rev    Revision number of source file.
rdate    Revision date of source file.
aut    Author of routine.


call find_namelist_in_file(namelist_file_name, nml_name, iunit, [, write_to_logfile_in])
 character(len=*), intent(in)           :: namelist_file_name
 character(len=*), intent(in)           :: nml_name
 integer,          intent(out)           :: iunit
 logical, optional, intent(in)          :: write_to_logfile_in
 

Description

Opens the file namelist_file_name if it exists on unit iunit. A fatal error occurs if the file does not exist (DART requires an input.nml to be available, even if it contains no values). Searches through the file for a line containing ONLY the string &nml_name (for instance &filter_nml if nml_name is "filter_nml"). If this line is found, the file is rewound and the routine returns. Otherwise, a fatal error message is issued.

namelist    Name of file assumed to hold the namelist.
nml_name    Name of the namelist to be searched for in the file, for instance, filter_nml.
iunit    Channel number on which file is opened.
write_to_logfile_in    When the namelist for the utilities module is read, the logfile has not yet been open because its name is in the namelist. If errors are found, have to write to standard out. So, when utilities module calls this internally, this optional argument is set to false. For all other applications, it is normally not used (default is false).


call check_namelist_read(iunit, iostat_in, nml_name, [, write_to_logfile_in])
 integer, intent(in)                    :: iunit
 integer, intent(in)                    :: iostat_in
 character(len=*), intent(in)           :: nml_name
 character(len=*), optional, intent(in) :: write_to_logfile_in
 

Description

Once a namelist has been read from an opened namelist file, this routine checks for possible errors i the read. If the namelist read was successful, the file opened on iunit is closed and the routine returns. If iostat is not zero, an attempt is made to rewind the file on iunit and read the last line that was successfully read. If this can be done, this last line is printed with the preamble "INVALID NAMELIST ENTRY". If the attempt to read the line after rewinding fails, it is assumed that the original read (before the call to this subroutine) failed by reaching the end of the file. An error message stating that the namelist started but was never terminated is issued.

iunit    Channel number on which file is opened.
iostat_in    Error status return from an attempted read of a namelist from this file.
nml_name    The name of the namelist that is being read (for instance filter_nml.
write_to_logfile_in    When the namelist for the utilities module is read, the logfile has not yet been open because its name is in the namelist. If errors are found, have to write to standard out. So, when utilities module calls this internally, this optional argument is set to false. For all other applications, it is normally not used (default is false).


 integer :: E_DBG, DEBUG
 integer :: E_MSG, MESSAGE
 integer :: E_WARN, WARNING
 integer :: E_ERR, FATAL
 

Description

    Severity levels to be passed to error handler. Levels are debug, message, warning and fatal. The namelist parameter TERMLEVEL can be used to control at which level program termination should occur.


integer :: logfileunit

Description

logfileunit    Unit opened to file for diagnostic output.


call initialize_utilities()
 

Description

Reads the namelist and opens the logfile. Records the values of the namelist and registers this module.



call finalize_utilities()
 

Description

Closes the logfile; using utilities after this call is a bad idea.



call dump_unit_attributes(iunit)
 integer, intent(in) :: iunit
 

Description

Writes all information about the status of the IO unit to the error handler with error level message.

iunit    Unit about which information is requested.


 integer :: E_DBG, DEBUG
 integer :: E_MSG, MESSAGE
 integer :: E_WARN, WARNING
 integer :: E_ERR, FATAL
 

Description

    Severity levels to be passed to error handler. Levels are debug, message, warning and fatal. The namelist parameter TERMLEVEL can be used to control at which level program termination should occur.




We adhere to the F90 standard of starting a namelist with an ampersand '&' and terminating with a slash '/'.

 namelist / utilities_nml /  TERMLEVEL, logfilename


 

Discussion

The namelist controls the way in which the error handler acts. In the default case, only calls with level E_ERR lead to program termination. If TERMLEVEL is set to E_WARN, then warnings or errors lead to termination. If TERMLEVEL is set to E_ERR + 1, then even errors don't lead to termination (be careful doing this).

This namelist is read in a file called input.nml

Contents Type Description
TERMLEVEL integer Level at which calls to error manager terminate program. Default: E_ERR
logfilename character(len=129) File to which the logfile is written. Default: dart_log.out




FILES




REFERENCES


ERROR CODES and CONDITIONS

RoutineMessageComment
get_unit No available units Unable to open enough IO channels
check_nml_error while reading namelist _____ Fatal error reading namelist. This could be caused by having an entry in the namelist input file that is not in the namelist, by having illegal values for namelist variables, or by a variety of other compiler dependent problems.
find_namelist_in_file Namelist entry &____ must exist in namelist_nml. There must be an entry for the required namelist, for instance &filter_nml, in the input.nml namelist file. Even if no values are to be changed from the default, an entry like &filter_nml followed by a line containing only / is required.
find_namelist_in_file Namelist input file: input.nml must exist The namelist input file (usually input.nml) must exist.
check_namelist_read INVALID NAMELIST ENTRY: ___ in namelist ____ While reading the namelist, either a bad entry was found or an end of file was encountered. The most confusing case is when a namelist is being read successfully but is not appropriately terminated with a /. The line printed out by the error message will be the start of the next namelist in the input.nml file in this case.



KNOWN BUGS




FUTURE PLANS




PRIVATE COMPONENTS