fms_mod

The fms module provides routines that are commonly used by most FMS modules. More...

Data Types
interface	fms_c2f_string
	Converts a C string to a Fortran string. More...
type	nml_errors_type
	Namelist read error values. More...
interface	stringify
	Converts an array of real numbers to a string. More...

Functions/Subroutines
integer function, public	check_nml_error (IOSTAT, NML_NAME)
	Checks the iostat argument that is returned after reading a namelist and determines if the error code is valid. More...
subroutine, public	error_mesg (routine, message, level)
	Print notes, warnings and error messages; terminates program for warning and error messages. Usage of mpp_error is preferable. (use error levels NOTE,WARNING,FATAL, see example below) More...
subroutine, public	fms_end ()
	Calls the termination routines for all modules in the MPP package. More...
logical function, public	fms_error_handler (routine, message, err_msg)
	Facilitates the control of fatal error conditions. More...
subroutine, public	fms_init (localcomm, alt_input_nml_path)
	Initializes the FMS module and also calls the initialization routines for all modules in the MPP package. Will be called automatically if the user does not call it. More...
	monotonic_array_r4
	monotonic_array_r8
subroutine, private	nml_error_init
	Determines the IOSTAT error value for some common Namelist errors. Also checks if the compiler returns a non-zero status if there are multiple namelist records in a single file.
logical function, public	string_array_index (string, string_array, index)
	match the input character string to a string in an array/list of character strings More...
subroutine, public	write_version_number (version, tag, unit)
	Prints to the log file (or a specified unit) the version id string and tag name.

Variables
integer, public	clock_flag_default
character(len=16)	clock_flags ='NONE'
	Possible values are 'NONE', 'SYNC', or 'DETAILED'. SYNC will give accurate information on load balance of the clocked portion of code. DETAILED also turns on detailed message-passing performance diagnosis. Both SYNC and DETAILED will work correctly on innermost clock nest and distort outer clocks, and possibly the overall code time. See the mpp_mod module for more details.
character(len=16)	clock_grain = 'NONE'
	The level of clock granularity used for performance timing sections of code. Possible values in order of increasing detail are: 'NONE', 'COMPONENT', 'SUBCOMPONENT', 'MODULE_DRIVER', 'MODULE', 'ROUTINE', 'LOOP', and 'INFRA'. Code sections are defined using routines in MPP module: mpp_clock_id, mpp_clock_begin, and mpp_clock_end. The fms module makes these routines public. A list of timed code sections will be printed to STDOUT. See the mpp_mod module for more details.
logical, private	do_nml_error_init = .true.
integer	domains_stack_size = 0
	The size in words of the MPP_DOMAINS user stack. If domains_stack_size > 0, the following MPP_DOMAINS routine is called: call mpp_domains_set_stack_size (domains_stack_size). If domains_stack_size = 0 (default) then the default size set by mpp_domains_mod is used.
logical, private	fms_io
logical, private	fms_io_initialized = .FALSE.
logical, private	is
logical, private	make
logical	module_is_initialized = .FALSE.
integer, dimension(20), private	nml_error_codes
integer, private	num_nml_error_codes
logical, private	only
logical, public	print_memory_usage = .FALSE.
	If set to .TRUE., memory usage statistics will be printed at various points in the code. It is used to study memory usage, e.g to detect memory leaks.
logical	read_all_pe = .true.
	Read global data on all processors extracting local part needed (TRUE) or read global data on PE0 and broadcast to all PEs(FALSE).
integer	stack_size = 0
	The size in words of the MPP user stack. If stack_size > 0, the following MPP routine is called: call mpp_set_stack_size (stack_size). If stack_size = 0 (default) then the default size set by mpp_mod is used.
logical, private	sure
logical, private	to
logical, private	used
logical, private	version
character(len=8)	warning_level = 'warning'
	Sets the termination condition for the WARNING flag to interfaces error_mesg/mpp_error. set warning_level = 'fatal' (program crashes for warning messages) or 'warning' (prints warning message and continues).

Detailed Description

The fms module provides routines that are commonly used by most FMS modules.

Author

Bruce Wyman

Here is a summary of the functions performed by routines in the fms module.

1. Output module version numbers to a common (log) file using a common format.
   
2. Open specific types of files common to many FMS modules. These include namelist files, restart files, and 32-bit IEEE data files. There also is a matching interface to close the files. If other file types are needed the mpp_open and mpp_close interfaces in module mpp_io_mod must be used.
   
3. Read and write distributed data to simple native unformatted files. This type of file (called a restart file) is used to checkpoint model integrations for a subsequent restart of the run.
   
4. For convenience there are several routines published from the MPP module. These are routines for getting processor numbers, commonly used I/O unit numbers, error handling, and timing sections of code.

---

Data Type Documentation

fms_string_utils_mod::fms_c2f_string

interface fms_string_utils_mod::fms_c2f_string

Converts a C string to a Fortran string.

Definition at line 112 of file fms_string_utils.F90.

Private Member Functions
character(len=:) function, allocatable	cpointer_fortran_conversion (cstring)
	Converts a C-string returned from a TYPE(C_PTR) function to a fortran string with type character. More...
character(len=:) function, allocatable	cstring_fortran_conversion (cstring)
	Converts a C-string to a pointer and then to a Fortran string. More...

Member Function/Subroutine Documentation

cpointer_fortran_conversion()

character(len=:) function, allocatable cpointer_fortran_conversion ( type (c_ptr), intent(in)  cstring )

private

Converts a C-string returned from a TYPE(C_PTR) function to a fortran string with type character.

Parameters

[in]

cstring

Input C-pointer

Returns

The fortran string returned

Definition at line 208 of file fms_string_utils.F90.

cstring_fortran_conversion()

character(len=:) function, allocatable cstring_fortran_conversion ( character (kind=c_char), dimension (*), intent(in)  cstring )

private

Converts a C-string to a pointer and then to a Fortran string.

Parameters

[in]

cstring

Input C-string

Returns

The fortran string returned

Definition at line 200 of file fms_string_utils.F90.

fms_mod::nml_errors_type

type fms_mod::nml_errors_type

Namelist read error values.

Definition at line 238 of file fms.F90.

Collaboration diagram for nml_errors_type:

Private Attributes
integer	badtype1
integer	badtype2
integer	missingvar
integer	multiplenmlsinfile
integer	notinfile

fms_string_utils_mod::stringify

interface fms_string_utils_mod::stringify

Converts an array of real numbers to a string.

Definition at line 119 of file fms_string_utils.F90.

Private Member Functions
	stringify_1d_r4
	stringify_1d_r8
	stringify_2d_r4
	stringify_2d_r8
	stringify_3d_r4
	stringify_3d_r8

Function/Subroutine Documentation

check_nml_error()

integer function, public fms_mod::check_nml_error	(	integer, intent(in)	IOSTAT,
		character(len=*), intent(in)	NML_NAME
	)

Checks the iostat argument that is returned after reading a namelist and determines if the error code is valid.

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 and the program terminated.

The FMS allows multiple namelist records to reside in the same file. Use this interface to check the iostat argument that is returned after reading a record from the namelist file. If an invalid iostat value is detected this routine will produce a fatal error. See the NOTE below.

Some compilers will return non-zero iostat values when reading through files with multiple namelist. This routine will try skip these errors and only terminate for true namelist errors.

Examples

The following example checks if a file exists, reads a namelist input from that file, and checks for errors in that namelist. When the correct namelist is read and it has no errors the routine check_nml_error will return zero and the while loop will exit. This code segment should be used to read namelist files.

integer :: ierr, io
 
read (input_nml_file, fms_nml, iostat=io)
ierr = check_nml_error(io,'fms_nml')

Exceptions

FATAL,Unknown	error while reading namelist ...., (IOSTAT = ####) There was an error reading the namelist specified. Carefully examine all namelist and variables for anything incorrect (e.g. malformed, hidden characters).
FATAL,Unknown	namelist, or mistyped namelist variable in namelist ...., (IOSTAT = ####) The name list given doesn't exist in the namelist file, or a variable in the namelist is mistyped or isn't a namelist variable.

Parameters

[in]	iostat	The iostat value returned when reading a namelist record.
[in]	nml_name	The name of the namelist. This name will be printed if an error is encountered, otherwise the name is not used.

Definition at line 579 of file fms.F90.

error_mesg()

subroutine, public fms_mod::error_mesg	(	character(len=*), intent(in)	routine,
		character(len=*), intent(in)	message,
		integer, intent(in)	level
	)

Print notes, warnings and error messages; terminates program for warning and error messages. Usage of mpp_error is preferable. (use error levels NOTE,WARNING,FATAL, see example below)

Print notes, warnings and error messages; and terminates the program for error messages. This routine is a wrapper around mpp_error, and is provided for backward compatibility. This module also publishes mpp_error, users should try to use the mpp_error interface.

Example usage:

use fms_mod, only: error_mesg, fatal, note
call error_mesg ('fms_mod', 'initialization not called', fatal)
call error_mesg ('fms_mod', 'fms_mod message', note)

Parameters

[in]	routine	Routine name where the warning or error has occurred.
[in]	message	Warning or error message to be printed.
[in]	level	Level of severity; set to NOTE, WARNING, or FATAL Termination always occurs for FATAL, never for NOTE, and is settable for WARNING (see namelist).

Definition at line 497 of file fms.F90.

fms_end()

subroutine, public fms_mod::fms_end

Calls the termination routines for all modules in the MPP package.

Termination routine for the fms module. It also calls destructor routines for the mpp, mpp_domains, and mpp_io modules. If this routine is called more than once it will return silently. There are no arguments.

Definition at line 468 of file fms.F90.

fms_error_handler()

logical function, public fms_mod::fms_error_handler	(	character(len=*), intent(in)	routine,
		character(len=*), intent(in)	message,
		character(len=*), intent(out), optional	err_msg
	)

Facilitates the control of fatal error conditions.

When err_msg is present, message is copied into err_msg and the function returns a value of .true. Otherwise calls mpp_error to terminate execution. The intended use is as shown below.

Returns

true when err_msg is present

if(fms_error_handler(routine, message, err_msg)) return

Parameters

[in]	routine	Routine name where the fatal error has occurred.
[in]	message	fatal error message to be printed.
[out]	err_msg	When err_msg is present: err_msg = message

Definition at line 524 of file fms.F90.

fms_init()

subroutine, public fms_mod::fms_init	(	integer, intent(in), optional	localcomm,
		character(len=*), intent(in), optional	alt_input_nml_path
	)

Initializes the FMS module and also calls the initialization routines for all modules in the MPP package. Will be called automatically if the user does not call it.

Initialization routine for the fms module. It also calls initialization routines for the mpp, mpp_domains, and mpp_io modules. Although this routine will be called automatically by other fms_mod routines, users should explicitly call fms_init. If this routine is called more than once it will return silently. There are no arguments.

Exceptions

FATAL,invalid	entry for namelist variable warning_level The namelist variable warning_level must be either 'fatal' or 'warning'(case-insensitive)
FATAL,invalid	entry for namelist variable clock_grain The namelist variable clock_grain must be one of the following values: 'NONE', 'COMPONENT', 'SUBCOMPONENT', 'MODULE_DRIVER', 'MODULE', 'ROUTINE', 'LOOP', or 'INFRA' (case-insensitive).

Definition at line 331 of file fms.F90.

string_array_index()

logical function, public fms_mod::string_array_index	(	character(len=*), intent(in)	string,
		character(len=*), dimension(:), intent(in)	string_array,
		integer, intent(out), optional	index
	)

match the input character string to a string in an array/list of character strings

Returns

If an exact match was found then true is returned, otherwise false is returned.

Tries to find a match for a character string in a list of character strings. The match is case sensitive and disregards blank characters to the right of the string.

Examples

string = "def"
string_array = (/ "abcd", "def ", "fghi" /)
 
string_array_index( string, string_array, index )

Returns: TRUE, index = 2

Parameters

[in]	string	Character string of arbitrary length.
[in]	string_array	Array/list of character strings.
[out]	index	The index of string_array where the first match was found. If no match was found then index = 0.

Returns

If an exact match was found then TRUE is returned, otherwise FALSE is returned.

Definition at line 729 of file fms.F90.