Contact: | Jeff Anderson |
Reviewers: | |
Revision: | $Revision: 1.4 $ |
Release Name: | $Name: post_iceland $ |
Change Date: | $Date: 2005/10/17 19:48:47 $ |
Change history: | see CVS log |
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.
types_mod
Optional namelist interface &utilities_nml may be read from file input.nml.
logical :: file_exist character(len=*), intent(in) :: file_name
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. |
integer :: get_unit
Returns an unused unit number for IO.
get_unit | An unused unit number. |
integer :: check_nml_error integer, intent(in) :: iostat character(len=*), intent(in) :: nml_name
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. |
integer :: open_file character(len=*), intent(in) :: fname character(len=*), optional, intent(in) :: form character(len=*), optional, intent(in) :: action
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. |
character(len=*), optional, intent(in) :: string1 character(len=*), optional, intent(in) :: string2 character(len=*), optional, intent(in) :: string3 character(len=*), intent(in) :: pos
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. |
integer, intent(in) :: iunit
Closes the given unit number. If the unit is not open, nothing happens.
iunit | File unit to be closed. |
character(len=*), intent(in) :: src character(len=*), intent(in) :: rev character(len=*), intent(in) :: rdate
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. |
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
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. |
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
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). |
integer, intent(in) :: iunit integer, intent(in) :: iostat_in character(len=*), intent(in) :: nml_name character(len=*), optional, intent(in) :: write_to_logfile_in
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
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. |
logfileunit | Unit opened to file for diagnostic output. |
Reads the namelist and opens the logfile. Records the values of the namelist and registers this module.
Closes the logfile; using utilities after this call is a bad idea.
integer, intent(in) :: iunit
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
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
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 |
Routine | Message | Comment |
---|---|---|
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. |