PUBLIC INTERFACE ~ PUBLIC DATA ~ PUBLIC ROUTINES ~ NAMELIST ~ DIAGNOSTIC FIELDS ~ ERROR MESSAGES ~ REFERENCES ~ NOTES

## Module fms_io_mod

Contact: G.T. Nong , M.J. Harrison
Reviewers: M.J. Harrison , B. Wyman
Change History: WebCVS Log

#### OVERVIEW

This module is for writing and reading restart data in NetCDF format. fms_io_init must be called before the first write_data/read_data call For writing, fms_io_exit must be called after ALL write calls have been made. Typically, fms_io_init and fms_io_exit are placed in the main (driver) program while read_data and write_data can be called where needed. Presently, two combinations of threading and fileset are supported, users can choose one line of the following by setting namelist:
With the introduction of netCDF restart files, there is a need for a global switch to turn on/off netCDF restart options in all of the modules that deal with restart files. Here two more namelist variables (logical type) are introduced to fms_io
fms_netcdf_override fms_netcdf_restart
because default values of both flags are .true., the default behavior of the entire model is to use netCDF IO mode. To turn off netCDF restart, simply set fms_netcdf_restart to .false.
Fei.Liu@noaa.gov

    threading_read='multi', fileset_read='single', threading_write='multi', fileset_write='multi' (default)
    threading_read='multi', fileset_read='single', threading_write='single', fileset_write='single'

#### OTHER MODULES USED

         mpp_io_mod
    mpp_domains_mod
            mpp_mod
       platform_mod

#### PUBLIC INTERFACE

get_restart_io_mode:
fms_io_init:
fms_io_exit:
write_data:
field_size:
read_data:
open_namelist_file:
open_restart_file:
open_direct_file:
open_ieee32_file:
close_file:
set_domain:
nullify_domain:
return_domain:
get_domain_decomp:

#### PUBLIC DATA

None.

#### PUBLIC ROUTINES

1. #### get_restart_io_mode

       call get_restart_io_mode

   DESCRIPTION
     With the introduction of netCDF restart files, there is a need for a global switch to turn on/off netCDF restart options in all of the modules that deal with restart files. Here two more namelist variables (logical type) are introduced to fms_io
     fms_netcdf_override fms_netcdf_restart
     because default values of both flags are .true., the default behavior of the entire model is to use netCDF IO mode. To turn off netCDF restart, simply set fms_netcdf_restart to .false.
   INPUT/OUTPUT

     `do_netcdf_restart` | This the input argument that contains the individual module setting of restart IO mode. Upon return from this subroutine, this output argument contains the actual setting of restart IO mode the calling module will be using [logical]

2. #### fms_io_init

       call fms_io_init ()

   DESCRIPTION
     Initialize fms_io module

3. #### fms_io_exit

       call fms_io_exit

   DESCRIPTION
     This routine is called after ALL fields have been written to temporary files The result NETCDF files are created here.

4. #### write_data

       call write_data (filename, fieldname, data, domain)

   DESCRIPTION
     This subroutine performs writing "fieldname" to file "filename". All values of "fieldname" will be written to a temporary file. The final NETCDF file will be created only at a later step when the user calls fms_io_exit. Therefore, make sure that fms_io_exit is called after all fields have been written by this subroutine.
   INPUT

     `filename` | File name [character, dimension(*)]
     `fieldname` | Field name [character, dimension(*)]
     `data` | array containing data of fieldname [real]
     `domain` | domain of fieldname [domain, optional]

5. #### field_size

       call field_size (filename, fieldname, siz)

   DESCRIPTION
     Given filename and fieldname, this subroutine returns the size of field
   INPUT

     `filename` | File name [character, dimension(*)]
     `fieldname` | Field name [character, dimension(*)]

   OUTPUT

     `siz` | siz must be a dimension(4) array to retrieve the size of the field [integer, dimension(*)]
     `field_found` | if this flag is present, field_size will not abort if called for a non-existent field. Instead it will return T or F depending on whether or not the field was found. [logical, optional]

6. #### read_data

       call read_data (filename,fieldname,data,domain,timelevel)

   DESCRIPTION
     This routine performs reading "fieldname" stored in "filename". The data values of fieldname will be stored in "data" at the end of this routine. For fieldname with multiple timelevel just repeat the routine with explicit timelevel in each call.
   INPUT

     `filename` | File name [character, dimension(*)]
     `fieldname` | Field name [character, dimension(*)]
     `domain` | domain of fieldname [domain, optional]
     `timelevel` | time level of fieldname [integer, optional]

   OUTPUT

     `data` | array containing data of fieldname [real]

7. #### open_namelist_file

   DESCRIPTION
     Opens single namelist file for reading only by all PEs the default file opened is called "input.nml".
   INPUT

     `file` | name of the file to be opened [character]

   OUTPUT

     `unit` | unit number returned by this function [integer]

8. #### open_restart_file

   DESCRIPTION
     Opens single restart file for reading by all PEs or writing by root PE only the file has native format and no mpp header records.
   INPUT

     `file` | name of the file to be opened [character]
     `action` | action to be performed: can be 'read' or 'write' [character]

   OUTPUT

     `unit` | unit number returned by this function [integer]

9. #### open_direct_file

   DESCRIPTION
     Opens single direct access file for reading by all PEs or writing by root PE only the file has native format and no mpp header records.

10. #### open_ieee32_file

    DESCRIPTION
      Opens single 32-bit ieee file for reading by all PEs or writing by root PE only (writing is not recommended) the file has no mpp header records.
    INPUT

      `file` | name of the file to be opened [character]
      `action` | action to be performed: can be 'read' or 'write' [character]

    OUTPUT

      `unit` | unit number returned by this function [integer]

11. #### close_file

    DESCRIPTION
      Closes files that are opened by: open_namelist_file, open restart_file, and open_ieee32_file. Users should use mpp_close for other cases.
    INPUT

      `unit` | unit number of the file to be closed [integer]
      `status` | action to be performed: can be 'delete' [character, optional]

12. #### set_domain

    DESCRIPTION
      set_domain is called to save the domain2d data type prior to calling the distributed data I/O routines, read_data and write_data.
    INPUT

      `Domain2` | domain to be passed to routines in fms_io_mod, Current_domain will point to this Domain2 [domain2D]

13. #### nullify_domain

    DESCRIPTION
      Use to nulify domain that has been assigned by set_domain.

14. #### return_domain

    DESCRIPTION
      This routine is the reverse of set_domain above. This routine is called when users want to retrieve the domain2d that is used in fms_io_mod
    OUTPUT

      `domain2` | domain returned from fms_io_mod. [domain2D]

15. #### get_domain_decomp

    DESCRIPTION
      This will be a private routine with the next release. Users should get the domain decomposition from the domain2d data type.
    OUTPUT

      `x` | array containing beginning and ending indices of global and compute domain in x direction [integer]
      `y` | array containing beginning and ending indices of global and compute domain in y direction [integer]

#### NAMELIST

&fms_io_nml

`threading_read`

threading_read can be 'single' or 'multi'
[character]

`threading_write`

threading_write can be 'single' or 'multi'
[character]

`fileset_read`

fileset_read can be 'single' or 'multi'
[character]

`fileset_write`

fileset_write can be 'single' or 'multi'
[character]

`fms_netcdf_override`

.true. : fms_netcdf_restart overrides individual do_netcdf_restart value (default behavior) .false.: individual module settings has a precedence over the global setting, therefore fms_netcdf_restart is ignored
[logical]

`fms_netcdf_restart`

.true. : all modules deal with restart files will operate under netCDF mode (default behavior) .false.: all modules deal with restart files will operate under binary mode This flag is effective only when fms_netcdf_override is .true. When fms_netcdf_override is .false., individual module setting takes over.
[logical]

#### DATA SETS

None.

#### ERROR MESSAGES

None.

top