PUBLIC INTERFACE
use utilities_mod [, only: utilities_init, utilities_end,
error_mesg, NOTE, WARNING, FATAL,
file_exist, open_file, close_file,
read_data, write_data,
check_nml_error, print_version_number,
get_my_pe, get_num_pes, sync_all_pes,
get_root_pe,
set_domain, get_domain_decomp,
mpp_sum, mpp_min, mpp_max,
set_system_clock, check_system_clock
check_sum
utilities_init Initializes the utilities module and also the mpp_io
module (which initializes all mpp mods).
Will be called automatically if the user does not call it.
utilities_end Calls mpp_io_exit and check_system_clock.
error_mesg Print notes, warnings and error messages;
terminates program for warning and error messages.
(use error levels NOTE,WARNING,FATAL, see example below)
file_exist Function that returns whether a requested file name exists.
open_file Opens a given file name for I/O and returns a unit number.
If the file is already open the unit number is returned.
close_file Closes the requested unit number for I/O.
read_data Reads distributed data.
write_data Writes distributed data.
check_nml_error Checks the iostat returned when reading namelist input
and determines if the error code is valid, if not
the program is terminated.
write_version_number Prints out the version/id string and tag name
to a specified unit (presumably a log file).
set_domain Sets a pointer for a private utilities_mod
domain2d data type. This domain2d type is
used for subsequent calls by read_data and
write data.
get_domain_decomp Returns domain information from the domain2d
type set by the most recent call to set_domain.
set_system_clock Sets (or resets) a real-time clock.
This is automatically called by utilities_init.
check_system_clock Outputs the elapsed real-time since the last
call to set_system_clock (or utilities_init).
lowercase Convert character strings to all lower case
uppercase Convert character strings to all upper case
mpp_clock_init Sets up a identifier for performance timing
(similar to mpp_clock_id)
check_sum Returns a global (from all PEs) integer check sum.
--- Routines with exact functionality to mpp_mod routines ----
get_my_pe Returns the pe number. (mpp_pe)
get_root_pe Returns the root pe number. (mpp_root_pe)
get_num_pes Returns the total number pe's. (mpp_npes)
sync_all_pes Synchronizes pe's. (mpp_sync)
mpp_sum Compute summation. (mpp_sum)
mpp_min Find minimum. (mpp_min)
mpp_max Find maximum. (mpp_max)
check_sum Performs integer check sums (mpp_chksum)
mpp_clock_begin Initiates performance timing (mpp_clock_begin)
mpp_clock_end Terminates performance timing (mpp_clock_end)
PUBLIC ROUTINES
file_exist (file_name)
Input
file_name A file name (or path name) that is checked for existence.
[character]
Returns
This function returns a logical result.
If file_name exists the result is true, otherwise false is returned.
When reading a file, this function is often used in conjunction with
routine open_file.
---------------------------------------------------------------------
call error_mesg ( routine, message, level )
Input
routine Routine name where the warning or error has occurred.
[character]
message Warning or error message to be printed to standard output.
[character]
level Level of severity; set to NOTE, WARNING, or FATAL
Termination always occurs for FATAL, never for NOTE,
and is setable for WARNING (see namelist).
[integer]
Examples:
use utilities_mod, only: error_mesg, FATAL, NOTE
call error_mesg ('utilities_mod', 'initialization not called', FATAL)
call error_mesg ('utilities_mod', 'utilities_mod message', NOTE)
---------------------------------------------------------------------
check_nml_error ( iostat, nml_name )
Input
iostat The iostat value returned when reading a namelist record.
[integer]
nml_name The name of the namelist.
[character]
Returns
This function returns the input iostat value (integer) if it is an
allowable error code. If the iostat error code is not allowable,
an error message is printed to standard output and the program
terminated.
Note
See a table of possible iostat error codes
you may encounter on the Cray T90 or an SGI workstation.
Example
The following example check if a file exists, reads a namelist input
from that file, and checks for errors in that namelist.
if ( file_exist('input.nml') ) then
unit = open_file (file='input.nml')
ierr=1
do while (ierr /= 0)
read (unit, nml=moist_processes_nml, iostat=io, end=10)
ierr = check_nml_error(io,'moist_processes_nml')
enddo
10 close (unit)
endif
---------------------------------------------------------------------
unit = open_file ( file, form, action, access, threading, recl )
Input
file A file name (or path name).
[character]
Input (optional)
form The file format, use "formatted", "unformatted", "ascii",
"native", "ieee32", or "netcdf". Formatted and ascii are
the same, unformated and native are the same.
For ieee32 files, the iospec option for mpp_open is set
to the value in the utilities module namelist.
[character, default: "formatted"]
action I/O action to be performed, use "read", "write", or "append".
In this version there is no default, this argument must be
supplied when using the open_file interface.
[character, default: none ????]
access Direct or sequential file access, use "direct" or "sequential".
[character, default: "sequential"]
threading Single or multi-threading, use "single" or "multi".
For single threading, the no_header flag for mpp_open
is set to TRUE.
[character, default: "single"]
recl Record length for direct access files.
[integer, default: none]
Returns
This function opens the requested file and returns a fortran unit
number (integer). If the file is already open, the unit assigned to
that file is returned.
Example
When reading a file, this function is often used in conjunction with
routine file_exist.
if ( file_exist (`your_file') ) then
unit = open_file ( file='your_file', ..... )
endif
---------------------------------------------------------------------
call close_file ( unit, status )
---------------------------------------------------------------------
call write_version_number ( unit, version, tagname )
Input
unit The fortran unit number of an open formatted file.
This file is usually a log file.
[integer]
tagname The tag/name string usually returned by CVS
when checking out the code.
[character]
version The version/id string usually returned by CVS
when checking out code.
[character]
---------------------------------------------------------------------
call set_domain ( Domain2 )
Input
Domain2 Domain decomposition information.
[type(domain2d), target]
This interface must be called prior to calling interfaces
get_domain_decomp, read_data, or write_data.
---------------------------------------------------------------------
call get_domain_decomp ( x, y )
Input
x, y Arrays containing the current (since the last call to
set_domain) global and local start and end indices,
for the x- and y-axis, respectivly. The array values are
(/ global_start, global_end, local_start, local_end /).
[integer, dimension(4)]
---------------------------------------------------------------------
call read_data ( unit, data, end )
Input
unit The fortran unit number of an open unformatted file.
This value is returned by a previous call to open_file.
[integer]
Output
data Distributed data to be read.
The following data formats are allowed:
[real , dimension(isd:,jsd:) ]
[logical, dimension(isd:,jsd:) ]
[integer, dimension(isd:,jsd:) ]
[complex, dimension(isd:,jsd:) ]
[real , dimension(isd:,jsd:,:) ]
[complex, dimension(isd:,jsd:,:) ]
[real , dimension(isd:,jsd:,:,:)]
[complex, dimension(isd:,jsd:,:,:)]
NOTE: You must call set_domain before calling read_data.
---------------------------------------------------------------------
call write_data ( unit, data, end )
Input
unit The fortran unit number of an open unformatted file.
This value is returned by a previous call to open_file.
[integer]
data Distributed data to be written.
The following data formats are allowed:
[real , dimension(isd:,jsd:) ]
[logical, dimension(isd:,jsd:) ]
[integer, dimension(isd:,jsd:) ]
[complex, dimension(isd:,jsd:) ]
[real , dimension(isd:,jsd:,:) ]
[complex, dimension(isd:,jsd:,:) ]
[real , dimension(isd:,jsd:,:,:)]
[complex, dimension(isd:,jsd:,:,:)]
NOTE: You must call set_domain before calling write_data.
---------------------------------------------------------------------
call set_system_clock
There are no arguments.
---------------------------------------------------------------------
call check_system_clock ( string )
Optional Input
string An optional label that is printed before any timing numbers.
---------------------------------------------------------------------
call utilities_init
There are no arguments.
---------------------------------------------------------------------
call utilities_end
There are no arguments.
---------------------------------------------------------------------
string = lowercase ( cs )
INPUT
cs character string [character(len=*)]
RETURNS
string Character string that contain only lower case.
The characters "A-Z" are converted to "a-z".
---------------------------------------------------------------------
string = uppercase ( cs )
INPUT
cs character string [character(len=*)]
RETURNS
string Character string that contain only upper case.
The characters "a-z" are converted to "A-Z".
---------------------------------------------------------------------
id = mpp_clock_init ( module, routine, level )
INPUT
module Module name to be timed. [character]
routine Routine name and label for section of code to be timed.
[character]
level Level of timing. When this level equals "timing_level"
defined by namelist &utilities_nml a non-zero identification
integer will be returned.
[integer]
RETURNS
id The identification index returned by mpp_clocks_id.
A zero value is returned (turning clocks off) when input
argument level does not equal namelist variable timing_level.