MOM_file_parser.F90

Go to the documentation of this file.

module mom_file_parser
!***********************************************************************
!*                   GNU General Public License                        *
!* This file is a part of MOM.                                         *
!*                                                                     *
!* MOM is free software; you can redistribute it and/or modify it and  *
!* are expected to follow the terms of the GNU General Public License  *
!* as published by the Free Software Foundation; either version 2 of   *
!* the License, or (at your option) any later version.                 *
!*                                                                     *
!* MOM is distributed in the hope that it will be useful, but WITHOUT  *
!* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY  *
!* or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public    *
!* License for more details.                                           *
!*                                                                     *
!* For the full text of the GNU General Public License,                *
!* write to: Free Software Foundation, Inc.,                           *
!*           675 Mass Ave, Cambridge, MA 02139, USA.                   *
!* or see:   http://www.gnu.org/licenses/gpl.html                      *
!***********************************************************************

!********+*********+*********+*********+*********+*********+*********+**
!*                                                                     *
!*  By Robert Hallberg and Alistair Adcroft, updated 9/2013.           *
!*                                                                     *
!*    The subroutines here parse a set of input files for the value    *
!*  a named parameter and sets that parameter at run time.  Currently  *
!*  these files use use one of several formats:                        *
!*    #define VAR       ! To set the logical VAR to true.              *
!*    VAR = True        ! To set the logical VAR to true.              *
!*    #undef VAR        ! To set the logical VAR to false.             *
!*    VAR = False       ! To set the logical VAR to false.             *
!*    #define VAR 999   ! To set the real or integer VAR to 999.       *
!*    VAR = 999         ! To set the real or integer VAR to 999.       *
!*    #override VAR = 888 ! To override a previously set value.        *
!*    VAR = 1.1, 2.2, 3.3 ! To set an array of real values.            *
!*                                                                     *
!*  In addition, when set by the get_param interface, the values of    *
!*  parameters are automatically logged, along with defaults, units,   *
!*  and a description.  It is an error for a variable to be overridden *
!*  more than once, and MOM6 has a facility to check for unused lines  *
!*  to set variables, which may indicate miss-spelled or archaic       *
!*  parameters.  Parameter names are case-specific, and lines may use  *
!*  a F90 or C++ style comment, starting with ! or //.                 *
!*                                                                     *
!********+*********+*********+*********+*********+*********+*********+**

use mom_coms, only : root_pe, broadcast
use mom_error_handler, only : mom_error, fatal, warning, mom_mesg
use mom_error_handler, only : is_root_pe, stdlog, stdout
use mom_time_manager, only : set_time, get_time, time_type, get_ticks_per_second
use mom_time_manager, only : set_date, get_date
use mom_document, only : doc_param, doc_module, doc_init, doc_end, doc_type
use mom_document, only : doc_openblock, doc_closeblock
use mom_string_functions, only : left_int, left_ints, slasher
use mom_string_functions, only : left_real, left_reals

implicit none ; private

integer, parameter, public :: max_param_files = 5 ! Maximum number of parameter files.
integer, parameter :: input_str_length = 200 ! Maximum linelength in parameter file.
integer, parameter :: filename_length = 200  ! Maximum number of characters in
                                             ! file names.

! The all_PEs_read option should be eliminated with post-riga shared code.
logical :: all_pes_read = .false.

! Defaults
logical, parameter :: report_unused_default = .false.
logical, parameter :: unused_params_fatal_default = .false.
logical, parameter :: log_to_stdout_default = .false.
logical, parameter :: complete_doc_default = .true.
logical, parameter :: minimal_doc_default = .true.

type, private :: file_data_type ; private
  integer :: num_lines = 0
  character(len=INPUT_STR_LENGTH), pointer, dimension(:) :: line => null()
  logical,                         pointer, dimension(:) :: line_used => null()
end type file_data_type

type :: link_parameter ; private
  type(link_parameter), pointer :: next => null() ! Facilitates linked list
  character(len=80) :: name                       ! Parameter name
  logical :: hasissuedoverridewarning = .false.   ! Has a default value
end type link_parameter

type :: parameter_block ; private
  character(len=240) :: name = ''                 ! Parameter name
end type parameter_block

type, public :: param_file_type ; private
  integer  :: nfiles = 0            ! The number of open files.
  integer  :: iounit(max_param_files)   ! The unit number of an open file.
  character(len=FILENAME_LENGTH) :: filename(max_param_files) ! The names of the open files.
  logical  :: netcdf_file(max_param_files)! If true, the input file is in NetCDF.
                                    ! This is not yet implemented.
  type(file_data_type) :: param_data(max_param_files) ! Structures that contain
                                    ! the valid data lines from the parameter
                                    ! files, enabling all subsequent reads of
                                    ! parameter data to occur internally.
  logical  :: report_unused = report_unused_default ! If true, report any
                                    ! parameter lines that are not used in the run.
  logical  :: unused_params_fatal = unused_params_fatal_default  ! If true, kill
                                    ! the run if there are any unused parameters.
  logical  :: log_to_stdout = log_to_stdout_default ! If true, all log
                                    ! messages are also sent to stdout.
  logical  :: log_open = .false.    ! True if the log file has been opened.
  integer  :: stdout, stdlog        ! The units from stdout() and stdlog().
  character(len=240) :: doc_file    ! A file where all run-time parameters, their
                                    ! settings and defaults are documented.
  logical  :: complete_doc = complete_doc_default ! If true, document all
                                    ! run-time parameters.
  logical  :: minimal_doc = minimal_doc_default ! If true, document only those
                                    ! run-time parameters that differ from defaults.
  type(doc_type), pointer :: doc => null() ! A structure that contains information
                                    ! related to parameter documentation.
  type(link_parameter), pointer :: chain => null() ! Facilitates linked list
  type(parameter_block), pointer :: blockname => null() ! Name of active parameter block
end type param_file_type

public read_param, open_param_file, close_param_file, log_param, log_version
public doc_param, get_param
public clearparameterblock, openparameterblock, closeparameterblock

interface read_param
  module procedure read_param_int, read_param_real, read_param_logical, &
                   read_param_char, read_param_char_array, read_param_time, &
                   read_param_int_array, read_param_real_array
end interface
interface log_param
  module procedure log_param_int, log_param_real, log_param_logical, &
                   log_param_char, log_param_time, &
                   log_param_int_array, log_param_real_array
end interface
interface get_param
  module procedure get_param_int, get_param_real, get_param_logical, &
                   get_param_char, get_param_char_array, get_param_time, &
                   get_param_int_array, get_param_real_array
end interface
interface log_version
  module procedure log_version_cs, log_version_plain
end interface

contains

subroutine open_param_file(filename, CS, checkable, component, doc_file_dir)
  character(len=*),           intent(in) :: filename
  type(param_file_type),   intent(inout) :: CS
  logical,          optional, intent(in) :: checkable
  character(len=*), optional, intent(in) :: component
  character(len=*), optional, intent(in) :: doc_file_dir

  logical :: file_exists, unit_in_use, Netcdf_file, may_check
  integer :: ios, iounit, strlen, i
  character(len=240) :: doc_path
  type(parameter_block), pointer :: block

  may_check = .true. ; if (present(checkable)) may_check = checkable

  ! Check for non-blank filename
  strlen = len_trim(filename)
  if (strlen == 0) then
    call mom_error(fatal, "open_param_file: Input file has not been specified.")
  endif

  ! Check that this file has not already been opened
  if (cs%nfiles > 0) then
    inquire(file=trim(filename), number=iounit)
    if (iounit /= -1) then
      do i = 1, cs%nfiles
        if (cs%iounit(i) == iounit) then
          if (trim(cs%filename(1)) /= trim(filename)) then
            call mom_error(fatal, &
              "open_param_file: internal inconsistency! "//trim(filename)// &
              " is registered as open but has the wrong unit number!")
          else
            call mom_error(warning, &
              "open_param_file: file "//trim(filename)// &
              " has already been opened. This should NOT happen!"// &
              " Did you specify the same file twice in a namelist?")
            return
          endif ! filenames
        endif ! unit numbers
      enddo ! i
    endif
  endif

  ! Check that the file exists to readstdlog
  inquire(file=trim(filename), exist=file_exists)
  if (.not.file_exists) call mom_error(fatal, &
      "open_param_file: Input file "// trim(filename)//" does not exist.")

  netcdf_file = .false.
  if (strlen > 3) then
    if (filename(strlen-2:strlen) == ".nc") netcdf_file = .true.
  endif

  if (netcdf_file) &
    call mom_error(fatal,"open_param_file: NetCDF files are not yet supported.")

  if (all_pes_read .or. is_root_pe()) then
    ! Find an unused unit number.
    do iounit=10,512
      INQUIRE(iounit,opened=unit_in_use) ; if (.not.unit_in_use) exit
    enddo
    if (iounit >= 512) call mom_error(fatal, &
        "open_param_file: No unused file unit could be found.")

    ! Open the parameter file.
    open(iounit, file=trim(filename), access='SEQUENTIAL', &
         form='FORMATTED', action='READ', position='REWIND', iostat=ios)
    if (ios /= 0) call mom_error(fatal, "open_param_file: Error opening "// &
                                       trim(filename))
  else
    iounit = 1
  endif

  ! Store/register the unit and details
  i = cs%nfiles + 1
  cs%nfiles = i
  cs%iounit(i) = iounit
  cs%filename(i) = filename
  cs%NetCDF_file(i) = netcdf_file
  allocate(block) ; block%name = '' ; cs%blockName => block

  call mom_mesg("open_param_file: "// trim(filename)// &
                 " has been opened successfully.", 5)

  call populate_param_data(iounit, filename, cs%param_data(i))

  call read_param(cs,"SEND_LOG_TO_STDOUT",cs%log_to_stdout)
  call read_param(cs,"REPORT_UNUSED_PARAMS",cs%report_unused)
  call read_param(cs,"FATAL_UNUSED_PARAMS",cs%unused_params_fatal)
  cs%doc_file = "MOM_parameter_doc"
  if (present(component)) cs%doc_file = trim(component)//"_parameter_doc"
  call read_param(cs,"DOCUMENT_FILE", cs%doc_file)
  if (.not.may_check) then
    cs%report_unused = .false.
    cs%unused_params_fatal = .false.
  endif

  ! Open the log file.
  cs%stdlog = stdlog() ; cs%stdout = stdout()
  cs%log_open = (stdlog() > 0)

  doc_path = cs%doc_file
  if (len_trim(cs%doc_file) > 0) then
    cs%complete_doc = complete_doc_default
    call read_param(cs, "COMPLETE_DOCUMENTATION", cs%complete_doc)
    cs%minimal_doc = minimal_doc_default
    call read_param(cs, "MINIMAL_DOCUMENTATION", cs%minimal_doc)
    if (present(doc_file_dir)) then ; if (len_trim(doc_file_dir) > 0) then
      doc_path = trim(slasher(doc_file_dir))//trim(cs%doc_file)
    endif ; endif
  else
    cs%complete_doc = .false.
    cs%minimal_doc = .false.
  endif
  call doc_init(doc_path, cs%doc, cs%minimal_doc, cs%complete_doc)

end subroutine open_param_file

subroutine close_param_file(CS, quiet_close, component)
  type(param_file_type),   intent(inout) :: CS
  logical,          optional, intent(in) :: quiet_close
  character(len=*), optional, intent(in) :: component
! Arguments: CS - the param_file_type to close
!  (in,opt)  quiet_close - if present and true, do not do any logging with this
!                          call.
! This include declares and sets the variable "version".
#include "version_variable.h"
  character(len=128) :: docfile_default
  character(len=40)  :: mdl   ! This module's name.
  integer :: i, n, num_unused

  if (present(quiet_close)) then ; if (quiet_close) then
    do i = 1, cs%nfiles
      if (all_pes_read .or. is_root_pe()) close(cs%iounit(i))
      call mom_mesg("close_param_file: "// trim(cs%filename(i))// &
                    " has been closed successfully.", 5)
      cs%iounit(i) = -1
      cs%filename(i) = ''
      cs%NetCDF_file(i) = .false.
      deallocate (cs%param_data(i)%line)
      deallocate (cs%param_data(i)%line_used)
    enddo
    cs%log_open = .false.
    call doc_end(cs%doc)
    return
  endif ; endif

  ! Log the parameters for the parser.
  mdl = "MOM_file_parser"
  call log_version(cs, mdl, version, "")
  call log_param(cs, mdl, "SEND_LOG_TO_STDOUT", &
                        cs%log_to_stdout, &
                 "If true, all log messages are also sent to stdout.", &
                 default=log_to_stdout_default)
  call log_param(cs, mdl, "REPORT_UNUSED_PARAMS", &
                        cs%report_unused, &
                 "If true, report any parameter lines that are not used \n"//&
                 "in the run.", default=report_unused_default)
  call log_param(cs, mdl, "FATAL_UNUSED_PARAMS", &
                        cs%unused_params_fatal, &
                 "If true, kill the run if there are any unused \n"//&
                 "parameters.", default=unused_params_fatal_default)
  docfile_default = "MOM_parameter_doc"
  if (present(component)) docfile_default = trim(component)//"_parameter_doc"
  call log_param(cs, mdl, "DOCUMENT_FILE", cs%doc_file, &
                 "The basename for files where run-time parameters, their\n"//&
                 "settings, units and defaults are documented. Blank will\n"//&
                 "disable all parameter documentation.", default=docfile_default)
  if (len_trim(cs%doc_file) > 0) then
    call log_param(cs, mdl, "COMPLETE_DOCUMENTATION", &
                   cs%complete_doc, &
                  "If true, all run-time parameters are\n"//&
                  "documented in "//trim(cs%doc_file)//&
                  ".all .", default=complete_doc_default)
    call log_param(cs, mdl, "MINIMAL_DOCUMENTATION", &
                   cs%minimal_doc, &
                  "If true, non-default run-time parameters are\n"//&
                  "documented in "//trim(cs%doc_file)//&
                  ".short .", default=minimal_doc_default)
  endif

  num_unused = 0
  do i = 1, cs%nfiles
    if (is_root_pe() .and. (cs%report_unused .or. &
                            cs%unused_params_fatal)) then
      ! Check for unused lines.
      do n=1,cs%param_data(i)%num_lines
        if (.not.cs%param_data(i)%line_used(n)) then
          num_unused = num_unused + 1
          if (cs%report_unused) &
            call mom_error(warning, "Unused line in "//trim(cs%filename(i))// &
                            " : "//trim(cs%param_data(i)%line(n)))
        endif
      enddo
    endif

    if (all_pes_read .or. is_root_pe()) close(cs%iounit(i))
    call mom_mesg("close_param_file: "// trim(cs%filename(i))// &
                  " has been closed successfully.", 5)
    cs%iounit(i) = -1
    cs%filename(i) = ''
    cs%NetCDF_file(i) = .false.
    deallocate (cs%param_data(i)%line)
    deallocate (cs%param_data(i)%line_used)
  enddo

  if (is_root_pe() .and. (num_unused>0) .and. cs%unused_params_fatal) &
    call mom_error(fatal, "Run stopped because of unused parameter lines.")

  cs%log_open = .false.
  call doc_end(cs%doc)

end subroutine close_param_file

subroutine populate_param_data(iounit, filename, param_data)
  integer,                 intent(in) :: iounit
  character(len=*),        intent(in) :: filename
  type(file_data_type), intent(inout) :: param_data

  character(len=INPUT_STR_LENGTH) :: line
  integer :: num_lines
  logical :: inMultiLineComment

! Find the number of keyword lines in a parameter file
! Allocate the space to hold the lines in param_data%line
! Populate param_data%line with the keyword lines from parameter file

  if (iounit <= 0) return

  if (all_pes_read .or. is_root_pe()) then
    ! rewind the parameter file
    rewind(iounit)

    ! count the number of valid entries in the parameter file
    num_lines = 0
    inmultilinecomment = .false.
    do while(.true.)
      read(iounit, '(a)', end=8, err=9) line
      line = replacetabs(line)
      if (inmultilinecomment) then
        if (closemultilinecomment(line)) inmultilinecomment=.false.
      else
        if (lastnoncommentnonblank(line)>0) num_lines = num_lines + 1
        if (openmultilinecomment(line)) inmultilinecomment=.true.
      endif
    enddo ! while (.true.)
 8  continue ! get here when read() reaches EOF

    if (inmultilinecomment .and. is_root_pe()) &
      call mom_error(fatal, 'MOM_file_parser : A C-style multi-line comment '// &
                      '(/* ... */) was not closed before the end of '//trim(filename))

    ! allocate space to hold contents of the parameter file
    param_data%num_lines = num_lines
  endif  ! (is_root_pe())

  ! Broadcast the number of valid entries in parameter file
  if (.not. all_pes_read) then
    call broadcast(param_data%num_lines, root_pe())
  endif

  ! Set up the space for storing the actual lines.
  num_lines = param_data%num_lines
  allocate (param_data%line(num_lines))
  allocate (param_data%line_used(num_lines))
  param_data%line(:) = ' '
  param_data%line_used(:) = .false.

  ! Read the actual lines.
  if (all_pes_read .or. is_root_pe()) then
    ! rewind the parameter file
    rewind(iounit)

    ! Populate param_data%line
    num_lines = 0
    do while(.true.)
      read(iounit, '(a)', end=18, err=9) line
      line = replacetabs(line)
      if (inmultilinecomment) then
        if (closemultilinecomment(line)) inmultilinecomment=.false.
      else
        if (lastnoncommentnonblank(line)>0) then
          line = removecomments(line)
          line = simplifywhitespace(line(:len_trim(line)))
          num_lines = num_lines + 1
          param_data%line(num_lines) = line
        endif
        if (openmultilinecomment(line)) inmultilinecomment=.true.
      endif
    enddo ! while (.true.)
18  continue ! get here when read() reaches EOF

    if (num_lines /= param_data%num_lines) &
      call mom_error(fatal, 'MOM_file_parser : Found different number of '// &
                      'valid lines on second reading of '//trim(filename))
  endif  ! (is_root_pe())

  ! Broadcast the populated array param_data%line
  if (.not. all_pes_read) then
    call broadcast(param_data%line, input_str_length, root_pe())
  endif

  return

9 call mom_error(fatal, "MOM_file_parser : "//&
                  "Error while reading file "//trim(filename))

end subroutine populate_param_data

function openmultilinecomment(string)
  character(len=*), intent(in) :: string
  logical                      :: openMultiLineComment
! True if a /* appears on this line without a closing */
  integer :: icom, last
  openmultilinecomment = .false.
  last = lastnoncommentindex(string)+1
  icom = index(string(last:), "/*")
  if (icom > 0) then
    openmultilinecomment=.true.
    last = last+icom+1
  endif
  icom = index(string(last:), "*/") ; if (icom > 0) openmultilinecomment=.false.
end function openmultilinecomment

function closemultilinecomment(string)
  character(len=*), intent(in) :: string
  logical                      :: closeMultiLineComment
! True if a */ appears on this line
  closemultilinecomment = .false.
  if (index(string, "*/")>0) closemultilinecomment=.true.
end function closemultilinecomment

function lastnoncommentindex(string)
  character(len=*), intent(in) :: string
  integer                      :: lastNonCommentIndex
! Find position of last character before any comments
! This s/r is the only place where a comment needs to be defined
  integer :: icom, last
  last = len_trim(string)
  icom = index(string(:last), "!") ; if (icom > 0) last = icom-1 ! F90 style
  icom = index(string(:last), "//") ; if (icom > 0) last = icom-1 ! C+ style
  icom = index(string(:last), "/*") ; if (icom > 0) last = icom-1 ! C style
  lastnoncommentindex = last
end function lastnoncommentindex

function lastnoncommentnonblank(string)
  character(len=*), intent(in) :: string
  integer                      :: lastNonCommentNonBlank
! Find position of last non-blank character before any comments
  lastnoncommentnonblank = len_trim(string(:lastnoncommentindex(string))) ! Ignore remaining trailing blanks
end function lastnoncommentnonblank

function replacetabs(string)
  character(len=*), intent(in) :: string
  character(len=len(string))   :: replaceTabs
! Returns string with tabs replaced by a ablank
  integer :: i
  do i=1, len(string)
    if (string(i:i)==achar(9)) then
      replacetabs(i:i)=" "
    else
      replacetabs(i:i)=string(i:i)
    endif
  enddo
end function replacetabs

function removecomments(string)
  character(len=*), intent(in) :: string
  character(len=len(string))   :: removeComments
! Trims comments and leading blanks from string
  integer :: last
  removecomments=repeat(" ",len(string))
  last = lastnoncommentnonblank(string)
  removecomments(:last)=adjustl(string(:last)) ! Copy only the non-comment part of string
end function removecomments

function simplifywhitespace(string)
  character(len=*), intent(in) :: string
  character(len=len(string)+16)   :: simplifyWhiteSpace
! Constructs a string with all repeated whitespace replaced with single blanks
! and insert white space where it helps delineate tokens (e.g. around =)
  integer :: i,j
  logical :: nonBlank = .false., insidestring = .false.
  character(len=1) :: quoteChar=" "
  nonblank  = .false.; insidestring = .false. ! NOTE: For some reason this line is needed??
  i=0
  simplifywhitespace=repeat(" ",len(string)+16)
  do j=1,len_trim(string)
    if (insidestring) then ! Do not change formatting inside strings
      i=i+1
      simplifywhitespace(i:i)=string(j:j)
      if (string(j:j)==quotechar) insidestring=.false. ! End of string
    else ! The following is outside of string delimiters
      if (string(j:j)==" " .or. string(j:j)==achar(9)) then ! Space or tab
        if (nonblank) then ! Only copy a blank if the preceeding character was non-blank
          i=i+1
          simplifywhitespace(i:i)=" " ! Not string(j:j) so that tabs are replace by blanks
          nonblank=.false.
        endif
      elseif (string(j:j)=='"' .or. string(j:j)=="'") then ! Start a sting
        i=i+1
        simplifywhitespace(i:i)=string(j:j)
        insidestring=.true.
        quotechar=string(j:j) ! Keep copy of starting quote
        nonblank=.true.       ! For exit from string
      elseif (string(j:j)=='=') then
        ! Insert spaces if this character is "=" so that line contains " = "
        if (nonblank) then
          i=i+1
          simplifywhitespace(i:i)=" "
        endif
        i=i+2
        simplifywhitespace(i-1:i)=string(j:j)//" "
        nonblank=.false.
      else ! All other characters
        i=i+1
        simplifywhitespace(i:i)=string(j:j)
        nonblank=.true.
      endif
    endif ! if (insideString)
  enddo ! j
  if (insidestring) then ! A missing close quote should be flagged
    if (is_root_pe()) call mom_error(fatal, &
      "There is a mismatched quote in the parameter file line: "// &
      trim(string))
  endif
end function simplifywhitespace

subroutine read_param_int(CS, varname, value, fail_if_missing)
  type(param_file_type),  intent(in) :: CS
  character(len=*),       intent(in) :: varname
  integer,             intent(inout) :: value
  logical,      optional, intent(in) :: fail_if_missing
! This subroutine determines the value of an integer model parameter
! from a parameter file. The arguments are the unit of the open file
! which is to be read, the (case-sensitive) variable name, the variable
! where the value is to be stored, and (optionally) a flag indicating
! whether to fail if this parameter can not be found.
  character(len=INPUT_STR_LENGTH) :: value_string(1)
  logical            :: found, defined

  call get_variable_line(cs, varname, found, defined, value_string)
  if (found .and. defined .and. (len_trim(value_string(1)) > 0)) then
    read(value_string(1),*,err = 1001) value
  else
    if (present(fail_if_missing)) then ; if (fail_if_missing) then
      if (.not.found) then
        call mom_error(fatal,'read_param_int: Unable to find variable '//trim(varname)// &
                             ' in any input files.')
      else
        call mom_error(fatal,'read_param_int: Variable '//trim(varname)// &
                             ' found but not set in input files.')
      endif
    endif ; endif
  endif
  return
 1001 call mom_error(fatal,'read_param_int: read error for integer variable '//trim(varname)// &
                             ' parsing "'//trim(value_string(1))//'"')
end subroutine read_param_int

subroutine read_param_int_array(CS, varname, value, fail_if_missing)
  type(param_file_type),  intent(in) :: CS
  character(len=*),       intent(in) :: varname
  integer,             intent(inout) :: value(:)
  logical,      optional, intent(in) :: fail_if_missing
! This subroutine determines the value of an integer model parameter
! from a parameter file. The arguments are the unit of the open file
! which is to be read, the (case-sensitive) variable name, the variable
! where the value is to be stored, and (optionally) a flag indicating
! whether to fail if this parameter can not be found.
  character(len=INPUT_STR_LENGTH) :: value_string(1)
  logical            :: found, defined

  call get_variable_line(cs, varname, found, defined, value_string)
  if (found .and. defined .and. (len_trim(value_string(1)) > 0)) then
    read(value_string(1),*,end=991,err=1002) value
 991 return
  else
    if (present(fail_if_missing)) then ; if (fail_if_missing) then
      if (.not.found) then
        call mom_error(fatal,'read_param_int_array: Unable to find variable '//trim(varname)// &
                             ' in any input files.')
      else
        call mom_error(fatal,'read_param_int_array: Variable '//trim(varname)// &
                             ' found but not set in input files.')
      endif
    endif ; endif
  endif
  return
 1002 call mom_error(fatal,'read_param_int_array: read error for integer array '//trim(varname)// &
                             ' parsing "'//trim(value_string(1))//'"')
end subroutine read_param_int_array

subroutine read_param_real(CS, varname, value, fail_if_missing)
  type(param_file_type),  intent(in) :: CS
  character(len=*),       intent(in) :: varname
  real,                intent(inout) :: value
  logical,      optional, intent(in) :: fail_if_missing
! This subroutine determines the value of an integer model parameter
! from a parameter file. The arguments are the unit of the open file
! which is to be read, the (case-sensitive) variable name, the variable
! where the value is to be stored, and (optionally) a flag indicating
! whether to fail if this parameter can not be found.
  character(len=INPUT_STR_LENGTH) :: value_string(1)
  logical            :: found, defined

  call get_variable_line(cs, varname, found, defined, value_string)
  if (found .and. defined .and. (len_trim(value_string(1)) > 0)) then
    read(value_string(1),*,err=1003) value
  else
    if (present(fail_if_missing)) then ; if (fail_if_missing) then
      if (.not.found) then
        call mom_error(fatal,'read_param_real: Unable to find variable '//trim(varname)// &
                             ' in any input files.')
      else
        call mom_error(fatal,'read_param_real: Variable '//trim(varname)// &
                             ' found but not set in input files.')
      endif
    endif ; endif
  endif
  return
 1003 call mom_error(fatal,'read_param_real: read error for real variable '//trim(varname)// &
                             ' parsing "'//trim(value_string(1))//'"')
end subroutine read_param_real

subroutine read_param_real_array(CS, varname, value, fail_if_missing)
  type(param_file_type),  intent(in) :: CS
  character(len=*),       intent(in) :: varname
  real,                intent(inout) :: value(:)
  logical,      optional, intent(in) :: fail_if_missing
! This subroutine determines the value of an integer model parameter
! from a parameter file. The arguments are the unit of the open file
! which is to be read, the (case-sensitive) variable name, the variable
! where the value is to be stored, and (optionally) a flag indicating
! whether to fail if this parameter can not be found.
  character(len=INPUT_STR_LENGTH) :: value_string(1)
  logical                         :: found, defined

  call get_variable_line(cs, varname, found, defined, value_string)
  if (found .and. defined .and. (len_trim(value_string(1)) > 0)) then
    read(value_string(1),*,end=991,err=1004) value
 991 return
  else
    if (present(fail_if_missing)) then ; if (fail_if_missing) then
      if (.not.found) then
        call mom_error(fatal,'read_param_real_array: Unable to find variable '//trim(varname)// &
                             ' in any input files.')
      else
        call mom_error(fatal,'read_param_real_array: Variable '//trim(varname)// &
                             ' found but not set in input files.')
      endif
    endif ; endif
  endif
  return
 1004 call mom_error(fatal,'read_param_real_array: read error for real array '//trim(varname)// &
                             ' parsing "'//trim(value_string(1))//'"')
end subroutine read_param_real_array

subroutine read_param_char(CS, varname, value, fail_if_missing)
  type(param_file_type),  intent(in) :: CS
  character(len=*),       intent(in) :: varname
  character(len=*),    intent(inout) :: value
  logical,      optional, intent(in) :: fail_if_missing
! This subroutine determines the value of an integer model parameter
! from a parameter file. The arguments are the unit of the open file
! which is to be read, the (case-sensitive) variable name, the variable
! where the value is to be stored, and (optionally) a flag indicating
! whether to fail if this parameter can not be found.
  character(len=INPUT_STR_LENGTH) :: value_string(1)
  logical            :: found, defined

  call get_variable_line(cs, varname, found, defined, value_string)
  if (found) then
    value = trim(strip_quotes(value_string(1)))
  elseif (present(fail_if_missing)) then ; if (fail_if_missing) then
    call mom_error(fatal,'Unable to find variable '//trim(varname)// &
                         ' in any input files.')
  endif ; endif

end subroutine read_param_char

subroutine read_param_char_array(CS, varname, value, fail_if_missing)
  type(param_file_type),  intent(in) :: CS
  character(len=*),       intent(in) :: varname
  character(len=*),    intent(inout) :: value(:)
  logical,      optional, intent(in) :: fail_if_missing
! This subroutine determines the value of an integer model parameter
! from a parameter file. The arguments are the unit of the open file
! which is to be read, the (case-sensitive) variable name, the variable
! where the value is to be stored, and (optionally) a flag indicating
! whether to fail if this parameter can not be found.
  character(len=INPUT_STR_LENGTH) :: value_string(1), loc_string
  logical            :: found, defined
  integer            :: i, i_out

  call get_variable_line(cs, varname, found, defined, value_string)
  if (found) then
    loc_string = trim(value_string(1))
    i = index(loc_string,",")
    i_out = 1
    do while(i>0)
      value(i_out) = trim(strip_quotes(loc_string(:i-1)))
      i_out = i_out+1
      loc_string = trim(adjustl(loc_string(i+1:)))
      i = index(loc_string,",")
    enddo
    if (len_trim(loc_string)>0) then
      value(i_out) = trim(strip_quotes(adjustl(loc_string)))
      i_out = i_out+1
    endif
    do i=i_out,SIZE(value) ; value(i) = " " ; enddo
  elseif (present(fail_if_missing)) then ; if (fail_if_missing) then
    call mom_error(fatal,'Unable to find variable '//trim(varname)// &
                         ' in any input files.')
  endif ; endif

end subroutine read_param_char_array

subroutine read_param_logical(CS, varname, value, fail_if_missing)
  type(param_file_type),  intent(in) :: CS
  character(len=*),       intent(in) :: varname
  logical,             intent(inout) :: value
  logical,      optional, intent(in) :: fail_if_missing
! This subroutine determines the value of an integer model parameter
! from a parameter file. The arguments are the unit of the open file
! which is to be read, the (case-sensitive) variable name, the variable
! where the value is to be stored, and (optionally) a flag indicating
! whether to fail if this parameter can not be found.
  character(len=INPUT_STR_LENGTH) :: value_string(1)
  logical            :: found, defined

  call get_variable_line(cs, varname, found, defined, value_string, paramislogical=.true.)
  if (found) then
    value = defined
  elseif (present(fail_if_missing)) then ; if (fail_if_missing) then
    call mom_error(fatal,'Unable to find variable '//trim(varname)// &
                         ' in any input files.')
  endif ; endif
end subroutine read_param_logical


subroutine read_param_time(CS, varname, value, timeunit, fail_if_missing, date_format)
  type(param_file_type),  intent(in) :: CS
  character(len=*),       intent(in) :: varname
  type(time_type),     intent(inout) :: value
  real,         optional, intent(in) :: timeunit
  logical,      optional, intent(in) :: fail_if_missing
  logical,     optional, intent(out) :: date_format
! This subroutine determines the value of an time-type model parameter
! from a parameter file. The arguments are the unit of the open file
! which is to be read, the (case-sensitive) variable name, the variable
! where the value is to be stored, and (optionally) a flag indicating
! whether to fail if this parameter can not be found.  The unique argument
! to read time is the number of seconds to use as the unit of time being read.
  character(len=INPUT_STR_LENGTH) :: value_string(1)
  character(len=240) :: err_msg
  logical            :: found, defined
  real               :: real_time, time_unit
  integer            :: days, secs, vals(7)

  if (present(date_format)) date_format = .false.

  call get_variable_line(cs, varname, found, defined, value_string)
  if (found .and. defined .and. (len_trim(value_string(1)) > 0)) then
    ! Determine whether value string should be parsed for a real number
    ! or a date, in either a string format or a comma-delimited list of values.
    if ((index(value_string(1),'-') > 0) .and. &
        (index(value_string(1),'-',back=.true.) > index(value_string(1),'-'))) then
      ! There are two dashes, so this must be a date format.
      value = set_date(value_string(1), err_msg=err_msg)
      if (len_trim(err_msg) > 0) call mom_error(fatal,'read_param_time: '//&
          trim(err_msg)//' in integer list read error for time-type variable '//&
          trim(varname)// ' parsing "'//trim(value_string(1))//'"')
      if (present(date_format)) date_format = .true.
    elseif (index(value_string(1),',') > 0) then
      ! Initialize vals with an invalid date.
      vals(:) = (/ -999, -999, -999, 0, 0, 0, 0 /)
      read(value_string(1),*,end=995,err=1005) vals
     995 continue
      if ((vals(1) < 0) .or. (vals(2) < 0) .or. (vals(3) < 0)) &
        call mom_error(fatal,'read_param_time: integer list read error for time-type variable '//&
                       trim(varname)// ' parsing "'//trim(value_string(1))//'"')
      value = set_date(vals(1), vals(2), vals(3), vals(4), vals(5), vals(6), &
                       vals(7), err_msg=err_msg)
      if (len_trim(err_msg) > 0) call mom_error(fatal,'read_param_time: '//&
          trim(err_msg)//' in integer list read error for time-type variable '//&
          trim(varname)// ' parsing "'//trim(value_string(1))//'"')
      if (present(date_format)) date_format = .true.
    else
      time_unit = 1.0 ; if (present(timeunit)) time_unit = timeunit
      read( value_string(1), *) real_time
      days = int(real_time*(time_unit/86400.0))
      secs = int(floor((real_time*(time_unit/86400.0)-days)*86400.0 + 0.5))
      value = set_time(secs, days)
   endif
  else
    if (present(fail_if_missing)) then ; if (fail_if_missing) then
      if (.not.found) then
        call mom_error(fatal,'Unable to find variable '//trim(varname)// &
                             ' in any input files.')
      else
        call mom_error(fatal,'Variable '//trim(varname)// &
                             ' found but not set in input files.')
      endif
    endif ; endif
  endif
  return
 1005 call mom_error(fatal,'read_param_time: read error for time-type variable '//&
                           trim(varname)// ' parsing "'//trim(value_string(1))//'"')
end subroutine read_param_time

function strip_quotes(val_str)
  character(len=*) :: val_str
  character(len=INPUT_STR_LENGTH) :: strip_quotes
  ! Local variables
  integer :: i
  strip_quotes = val_str
  i = index(strip_quotes,achar(34)) ! Double quote
  do while (i>0)
    if (i > 1) then ; strip_quotes = strip_quotes(:i-1)//strip_quotes(i+1:)
    else ; strip_quotes = strip_quotes(2:) ; endif
    i = index(strip_quotes,achar(34)) ! Double quote
  enddo
  i = index(strip_quotes,achar(39)) ! Single quote
  do while (i>0)
    if (i > 1) then ; strip_quotes = strip_quotes(:i-1)//strip_quotes(i+1:)
    else ; strip_quotes = strip_quotes(2:) ; endif
    i = index(strip_quotes,achar(39)) ! Single quote
  enddo
end function strip_quotes

subroutine get_variable_line(CS, varname, found, defined, value_string, paramIsLogical)
  type(param_file_type),  intent(in) :: CS
  character(len=*),       intent(in) :: varname
  logical,               intent(out) :: found, defined
  character(len=*),      intent(out) :: value_string(:)
  logical, optional,      intent(in) :: paramIsLogical

  character(len=INPUT_STR_LENGTH) :: val_str, lname, origLine
  character(len=INPUT_STR_LENGTH) :: line, continuationBuffer, blockName
  character(len=FILENAME_LENGTH)  :: filename
  integer            :: is, id, isd, isu, ise, iso, verbose, ipf
  integer            :: last, last1, ival, oval, max_vals, count, contBufSize
  character(len=52)  :: set
  logical            :: found_override, found_equals
  logical            :: found_define, found_undef
  logical            :: force_cycle, defined_in_line, continuedLine
  logical            :: variableKindIsLogical, valueIsSame
  logical            :: inWrongBlock, fullPathParameter
  logical, parameter :: requireNamedClose = .false.
  set = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
  continuationbuffer = repeat(" ",input_str_length)
  contbufsize = 0
  verbose = 1

  variablekindislogical=.false.
  if (present(paramislogical)) variablekindislogical = paramislogical

  ! Find the first instance (if any) where the named variable is found, and
  ! return variables indicating whether this variable is defined and the string
  ! that contains the value of this variable.
  found = .false.
  oval = 0; ival = 0;
  max_vals = SIZE(value_string)
  do is=1,max_vals ; value_string(is) = " " ; enddo

  paramfile_loop: do ipf = 1, cs%nfiles
    filename = cs%filename(ipf)
    continuedline = .false.
    blockname = ''

    ! Scan through each line of the file
    do count = 1, cs%param_data(ipf)%num_lines
      line = cs%param_data(ipf)%line(count)
      last = len_trim(line)

      last1 = max(1,last)
      ! Check if line ends in continuation character (either & or \)
      ! Note achar(92) is a backslash
      if (line(last1:last1) == achar(92).or.line(last1:last1) == "&") then
        continuationbuffer(contbufsize+1:contbufsize+len_trim(line))=line(:last-1)
        contbufsize=contbufsize + len_trim(line)-1
        continuedline = .true.
        if (count==cs%param_data(ipf)%num_lines .and. is_root_pe()) &
           call mom_error(fatal, "MOM_file_parser : the last line"// &
                 " of the file ends in a continuation character but"// &
                 " there are no more lines to read. "// &
                 " Line: '"//trim(line(:last))//"'"//&
                 " in file "//trim(filename)//".")
        cycle ! cycle inorder to append the next line of the file
      elseif (continuedline) then
        ! If we reached this point then this is the end of line continuation
        continuationbuffer(contbufsize+1:contbufsize+len_trim(line))=line(:last)
        line = continuationbuffer
        continuationbuffer=repeat(" ",input_str_length) ! Clear for next use
        contbufsize = 0
        continuedline = .false.
        last = len_trim(line)
      endif

      origline = trim(line) ! Keep original for error messages

      ! Check for '#override' at start of line
      found_override = .false.; found_define = .false.; found_undef = .false.
      iso = index(line(:last), "#override " )!; if (is > 0) found_override = .true.
      if (iso>1) call mom_error(fatal, "MOM_file_parser : #override was found "// &
                 " but was not the first keyword."// &
                 " Line: '"//trim(line(:last))//"'"//&
                 " in file "//trim(filename)//".")
      if (iso==1) then
        found_override = .true.
        if (index(line(:last), "#override define ")==1) found_define = .true.
        if (index(line(:last), "#override undef ")==1) found_undef = .true.
        line = trim(adjustl(line(iso+10:last))); last = len_trim(line)
      endif

      ! Check for start of fortran namelist, ie. '&namelist'
      if (index(line(:last),'&')==1) then
        iso=index(line(:last),' ')
        if (iso>0) then ! possibly simething else on this line
          blockname = pushblocklevel(blockname,line(2:iso-1))
          line=trim(adjustl(line(iso:last)))
          last=len_trim(line)
          if (last==0) cycle ! nothing else on this line
        else ! just the namelist on this line
          if (len_trim(blockname)>0) then
            blockname = trim(blockname) // '%' //trim(line(2:last))
          else
            blockname = trim(line(2:last))
          endif
          call flag_line_as_read(cs%param_data(ipf)%line_used,count)
          cycle
        endif
      endif

      ! Newer form of parameter block, block%, %block or block%param or
      iso=index(line(:last),'%')
      fullpathparameter = .false.
      if (iso==1) then ! % is first character means this is a close
        if (len_trim(blockname)==0 .and. is_root_pe()) call mom_error(fatal, &
            'get_variable_line: An extra close block was encountered. Line="'// &
            trim(line(:last))//'"' )
        if (last>1 .and. trim(blockname)/=trim(line(2:last)) .and. is_root_pe()) &
            call mom_error(fatal, 'get_variable_line: A named close for a parameter'// &
            ' block did not match the open block. Line="'//trim(line(:last))//'"' )
        if (last==1 .and. requirenamedclose) & ! line = '%' is a generic (unnamed) close
            call mom_error(fatal, 'get_variable_line: A named close for a parameter'// &
            ' block is required but found "%". Block="'//trim(blockname)//'"' )
        blockname = popblocklevel(blockname)
        call flag_line_as_read(cs%param_data(ipf)%line_used,count)
      elseif (iso==last) then ! This is a new block if % is last character
        blockname = pushblocklevel(blockname, line(:iso-1))
        call flag_line_as_read(cs%param_data(ipf)%line_used,count)
      else ! This is of the form block%parameter = ... (full path parameter)
        iso=index(line(:last),'%',.true.)
        ! Check that the parameter block names on the line matches the state set by the caller
        if (iso>0 .and. trim(cs%blockName%name)==trim(line(:iso-1))) then
          fullpathparameter = .true.
          line = trim(line(iso+1:last)) ! Strip away the block name for subsequent processing
          last = len_trim(line)
        endif
      endif

      ! We should only interpret this line if this block is the active block
      inwrongblock = .false.
      if (len_trim(blockname)>0) then ! In a namelist block in file
        if (trim(cs%blockName%name)/=trim(blockname)) inwrongblock = .true. ! Not in the required block
      endif
      if (len_trim(cs%blockName%name)>0) then ! In a namelist block in the model
        if (trim(cs%blockName%name)/=trim(blockname)) inwrongblock = .true. ! Not in the required block
      endif

      ! Check for termination of a fortran namelist (with a '/')
      if (line(last:last)=='/') then
        if (len_trim(blockname)==0 .and. is_root_pe()) call mom_error(fatal, &
            'get_variable_line: An extra namelist/block end was encountered. Line="'// &
            trim(line(:last))//'"' )
        blockname = popblocklevel(blockname)
        last = last - 1 ! Ignore the termination character from here on
      endif
      if (inwrongblock .and. .not. fullpathparameter) then
        if (index(" "//line(:last+1), " "//trim(varname)//" ")>0) &
          call mom_error(warning,"MOM_file_parser : "//trim(varname)// &
               ' found outside of block '//trim(cs%blockName%name)//'%. Ignoring.')
        cycle
      endif

      ! Determine whether this line mentions the named parameter or not
      if (index(" "//line(:last)//" ", " "//trim(varname)//" ") == 0) cycle

      ! Detect keywords
      found_equals = .false.
      isd = index(line(:last), "define" )!; if (isd > 0) found_define = .true.
      isu = index(line(:last), "undef" )!; if (isu > 0) found_undef = .true.
      ise = index(line(:last), " = " ); if (ise > 1) found_equals = .true.
      if (index(line(:last), "#define ")==1) found_define = .true.
      if (index(line(:last), "#undef ")==1) found_undef = .true.

      ! Check for missing, mutually exclusive or incomplete keywords
      if (is_root_pe()) then
        if (.not. (found_define .or. found_undef .or. found_equals)) &
               call mom_error(fatal, "MOM_file_parser : the parameter name '"// &
                 trim(varname)//"' was found without define or undef."// &
                 " Line: '"//trim(line(:last))//"'"//&
                 " in file "//trim(filename)//".")
        if (found_define .and. found_undef) call mom_error(fatal, &
                 "MOM_file_parser : Both 'undef' and 'define' occur."// &
                 " Line: '"//trim(line(:last))//"'"//&
                 " in file "//trim(filename)//".")
        if (found_equals .and. (found_define .or. found_undef)) &
               call mom_error(fatal, &
                 "MOM_file_parser : Both 'a=b' and 'undef/define' syntax occur."// &
                 " Line: '"//trim(line(:last))//"'"//&
                 " in file "//trim(filename)//".")
        if (found_override .and. .not. (found_define .or. found_undef .or. found_equals)) &
               call mom_error(fatal, "MOM_file_parser : override was found "// &
                 " without a define or undef."// &
                 " Line: '"//trim(line(:last))//"'"//&
                 " in file "//trim(filename)//".")
      endif

      ! Interpret the line and collect values, if any
      if (found_define) then
        ! Move starting pointer to first letter of defined name.
        is = isd + 5 + scan(line(isd+6:last), set)

        id = scan(line(is:last), ' ')  ! Find space between name and value
        if ( id == 0 ) then
          ! There is no space so the name is simply being defined.
          lname = trim(line(is:last))
          if (trim(lname) /= trim(varname)) cycle
          val_str = " "
        else
          ! There is a string or number after the name.
          lname = trim(line(is:is+id-1))
          if (trim(lname) /= trim(varname)) cycle
          val_str = trim(adjustl(line(is+id:last)))
        endif
        found = .true. ; defined_in_line = .true.
      elseif (found_undef) then
        ! Move starting pointer to first letter of undefined name.
        is = isu + 4 + scan(line(isu+5:last), set)

        id = scan(line(is:last), ' ')  ! Find the first space after the name.
        if (id > 0) last = is + id - 1
        lname = trim(line(is:last))
        if (trim(lname) /= trim(varname)) cycle
        val_str = " "
        found = .true. ; defined_in_line = .false.
      elseif (found_equals) then
        ! Move starting pointer to first letter of defined name.
        is = scan(line(1:ise), set)
        lname = trim(line(is:ise-1))
        if (trim(lname) /= trim(varname)) cycle
        val_str = trim(adjustl(line(ise+3:last)))
        if (variablekindislogical) then ! Special handling for logicals
          read(val_str(:len_trim(val_str)),*) defined_in_line
        else
          defined_in_line = .true.
        endif
        found = .true.
      else
        call mom_error(fatal, "MOM_file_parser (non-root PE?): the parameter name '"// &
           trim(varname)//"' was found without an assignment, define or undef."// &
           " Line: '"//trim(line(:last))//"'"//" in file "//trim(filename)//".")
      endif

      ! This line has now been used.
      call flag_line_as_read(cs%param_data(ipf)%line_used,count)

      ! Detect inconsistencies
      force_cycle = .false.
      valueissame = (trim(val_str) == trim(value_string(max_vals)))
      if (found_override .and. (oval >= max_vals)) then
        if (is_root_pe()) then
          if ((defined_in_line .neqv. defined) .or. .not. valueissame) then
            call mom_error(fatal,"MOM_file_parser : "//trim(varname)// &
                     " found with multiple inconsistent overrides."// &
                     " Line A: '"//trim(value_string(max_vals))//"'"//&
                     " Line B: '"//trim(line(:last))//"'"//&
                     " in file "//trim(filename)//" caused the model failure.")
          else
            call mom_error(warning,"MOM_file_parser : "//trim(varname)// &
                     " over-ridden more times than is permitted."// &
                     " Line: '"//trim(line(:last))//"'"//&
                     " in file "//trim(filename)//" is being ignored.")
          endif
        endif
        force_cycle = .true.
      endif
      if (.not.found_override .and. (oval > 0)) then
        if (is_root_pe()) &
          call mom_error(warning,"MOM_file_parser : "//trim(varname)// &
                   " has already been over-ridden."// &
                   " Line: '"//trim(line(:last))//"'"//&
                   " in file "//trim(filename)//" is being ignored.")
        force_cycle = .true.
      endif
      if (.not.found_override .and. (ival >= max_vals)) then
        if (is_root_pe()) then
          if ((defined_in_line .neqv. defined) .or. .not. valueissame) then
            call mom_error(fatal,"MOM_file_parser : "//trim(varname)// &
                     " found with multiple inconsistent definitions."// &
                     " Line A: '"//trim(value_string(max_vals))//"'"//&
                     " Line B: '"//trim(line(:last))//"'"//&
                     " in file "//trim(filename)//" caused the model failure.")
          else
            call mom_error(warning,"MOM_file_parser : "//trim(varname)// &
                     " occurs more times than is permitted."// &
                     " Line: '"//trim(line(:last))//"'"//&
                     " in file "//trim(filename)//" is being ignored.")
          endif
        endif
        force_cycle = .true.
      endif
      if (force_cycle) cycle

      ! Store new values
      if (found_override) then
        oval = oval + 1
        value_string(oval) = trim(val_str)
        defined = defined_in_line
        if (verbose > 0 .and. ival > 0 .and. is_root_pe() .and. &
            .not. overridewarninghasbeenissued(cs%chain, trim(varname)) ) &
          call mom_error(warning,"MOM_file_parser : "//trim(varname)// &
                 " over-ridden.  Line: '"//trim(line(:last))//"'"//&
                 " in file "//trim(filename)//".")
      else ! (.not. found_overide)
        ival = ival + 1
        value_string(ival) = trim(val_str)
        defined = defined_in_line
        if (verbose > 1 .and. is_root_pe()) &
          call mom_error(warning,"MOM_file_parser : "//trim(varname)// &
                 " set.  Line: '"//trim(line(:last))//"'"//&
                 " in file "//trim(filename)//".")
      endif

    enddo ! CS%param_data(ipf)%num_lines

    if (len_trim(blockname)>0 .and. is_root_pe()) call mom_error(fatal, &
      'A namelist/parameter block was not closed. Last open block appears '// &
      'to be "'//trim(blockname)//'".')

  enddo paramfile_loop

end subroutine get_variable_line

subroutine flag_line_as_read(line_used,count)
  logical, dimension(:), pointer :: line_used
  integer,            intent(in) :: count
  line_used(count) = .true.
end subroutine flag_line_as_read

function overridewarninghasbeenissued(chain, varName)
  type(link_parameter), pointer    :: chain
  character(len=*),     intent(in) :: varName
  logical                          :: overrideWarningHasBeenIssued
! Returns true if an override warning has been issued for the variable varName
  type(link_parameter), pointer :: newLink, this
  overridewarninghasbeenissued = .false.
  this => chain
  do while( associated(this) )
    if (trim(varname) == trim(this%name)) then
      overridewarninghasbeenissued = .true.
      return
    endif
    this => this%next
  enddo
  allocate(newlink)
  newlink%name = trim(varname)
  newlink%hasIssuedOverrideWarning = .true.
  newlink%next => chain
  chain => newlink
end function overridewarninghasbeenissued

! The following subroutines write out to a log file.

!> Log the version of a module to a log file and/or stdout, and/or to the
!! parameter documentation file.
subroutine log_version_cs(CS, modulename, version, desc)
  type(param_file_type),      intent(in) :: CS         !< File parser type
  character(len=*),           intent(in) :: modulename !< Name of calling module
  character(len=*),           intent(in) :: version    !< Version string of module
  character(len=*), optional, intent(in) :: desc       !< Module description
  ! Local variables
  character(len=240) :: mesg

  mesg = trim(modulename)//": "//trim(version)
  if (is_root_pe()) then
    if (cs%log_open) write(cs%stdlog,'(a)') trim(mesg)
    if (cs%log_to_stdout) write(cs%stdout,'(a)') trim(mesg)
  endif

  if (present(desc)) call doc_module(cs%doc, modulename, desc)

end subroutine log_version_cs

!> Log the version of a module to a log file and/or stdout.
subroutine log_version_plain(modulename, version)
  character(len=*),           intent(in) :: modulename !< Name of calling module
  character(len=*),           intent(in) :: version    !< Version string of module
  ! Local variables
  character(len=240) :: mesg

  mesg = trim(modulename)//": "//trim(version)
  if (is_root_pe()) then
    write(stdlog(),'(a)') trim(mesg)
  endif

end subroutine log_version_plain

subroutine log_param_int(CS, modulename, varname, value, desc, units, &
                         default, layoutParam)
  type(param_file_type),      intent(in) :: CS
  character(len=*),           intent(in) :: modulename
  character(len=*),           intent(in) :: varname
  integer,                    intent(in) :: value
  character(len=*), optional, intent(in) :: desc, units
  integer,          optional, intent(in) :: default
  logical,          optional, intent(in) :: layoutParam
! This subroutine writes the value of an integer parameter to a log file,
! along with its name and the module it came from.
  character(len=240) :: mesg, myunits

  write(mesg, '("  ",a," ",a,": ",a)') trim(modulename), trim(varname), trim(left_int(value))
  if (is_root_pe()) then
    if (cs%log_open) write(cs%stdlog,'(a)') trim(mesg)
    if (cs%log_to_stdout) write(cs%stdout,'(a)') trim(mesg)
  endif

  myunits=" "; if (present(units)) write(myunits(1:240),'(A)') trim(units)
  if (present(desc)) &
    call doc_param(cs%doc, varname, desc, myunits, value, default, &
                   layoutparam=layoutparam)

end subroutine log_param_int

subroutine log_param_int_array(CS, modulename, varname, value, desc, &
                               units, default, layoutParam)
  type(param_file_type),      intent(in) :: CS
  character(len=*),           intent(in) :: modulename
  character(len=*),           intent(in) :: varname
  integer,                    intent(in) :: value(:)
  character(len=*), optional, intent(in) :: desc, units
  integer,          optional, intent(in) :: default
  logical,          optional, intent(in) :: layoutParam
! This subroutine writes the value of an integer parameter to a log file,
! along with its name and the module it came from.
  character(len=1320) :: mesg
  character(len=240) :: myunits

  write(mesg, '("  ",a," ",a,": ",A)') trim(modulename), trim(varname), trim(left_ints(value))
  if (is_root_pe()) then
    if (cs%log_open) write(cs%stdlog,'(a)') trim(mesg)
    if (cs%log_to_stdout) write(cs%stdout,'(a)') trim(mesg)
  endif

  myunits=" "; if (present(units)) write(myunits(1:240),'(A)') trim(units)
  if (present(desc)) &
    call doc_param(cs%doc, varname, desc, myunits, value, default, &
                   layoutparam=layoutparam)

end subroutine log_param_int_array

subroutine log_param_real(CS, modulename, varname, value, desc, units, &
                          default)
  type(param_file_type),      intent(in) :: CS
  character(len=*),           intent(in) :: modulename
  character(len=*),           intent(in) :: varname
  real,                       intent(in) :: value
  character(len=*), optional, intent(in) :: desc, units
  real,             optional, intent(in) :: default
! This subroutine writes the value of a real parameter to a log file,
! along with its name and the module it came from.
  character(len=240) :: mesg, myunits

  write(mesg, '("  ",a," ",a,": ",a)') &
    trim(modulename), trim(varname), trim(left_real(value))
  if (is_root_pe()) then
    if (cs%log_open) write(cs%stdlog,'(a)') trim(mesg)
    if (cs%log_to_stdout) write(cs%stdout,'(a)') trim(mesg)
  endif

  myunits="not defined"; if (present(units)) write(myunits(1:240),'(A)') trim(units)
  if (present(desc)) &
    call doc_param(cs%doc, varname, desc, myunits, value, default)

end subroutine log_param_real

subroutine log_param_real_array(CS, modulename, varname, value, desc, &
                                units, default)
  type(param_file_type),      intent(in) :: CS
  character(len=*),           intent(in) :: modulename
  character(len=*),           intent(in) :: varname
  real,                       intent(in) :: value(:)
  character(len=*), optional, intent(in) :: desc, units
  real,             optional, intent(in) :: default
! This subroutine writes the value of a real parameter to a log file,
! along with its name and the module it came from.
  character(len=1320) :: mesg
  character(len=240) :: myunits

 !write(mesg, '("  ",a," ",a,": ",ES19.12,99(",",ES19.12))') &
 !write(mesg, '("  ",a," ",a,": ",G,99(",",G))') &
 !  trim(modulename), trim(varname), value
  write(mesg, '("  ",a," ",a,": ",a)') &
    trim(modulename), trim(varname), trim(left_reals(value))
  if (is_root_pe()) then
    if (cs%log_open) write(cs%stdlog,'(a)') trim(mesg)
    if (cs%log_to_stdout) write(cs%stdout,'(a)') trim(mesg)
  endif

  myunits="not defined"; if (present(units)) write(myunits(1:240),'(A)') trim(units)
  if (present(desc)) &
    call doc_param(cs%doc, varname, desc, myunits, value, default)

end subroutine log_param_real_array

subroutine log_param_logical(CS, modulename, varname, value, desc, &
                             units, default, layoutParam)
  type(param_file_type),      intent(in) :: CS
  character(len=*),           intent(in) :: modulename
  character(len=*),           intent(in) :: varname
  logical,                    intent(in) :: value
  character(len=*), optional, intent(in) :: desc, units
  logical,          optional, intent(in) :: default
  logical,          optional, intent(in) :: layoutParam
! This subroutine writes the value of a logical parameter to a log file,
! along with its name and the module it came from.
  character(len=240) :: mesg, myunits

  if (value) then
    write(mesg, '("  ",a," ",a,": True")') trim(modulename), trim(varname)
  else
    write(mesg, '("  ",a," ",a,": False")') trim(modulename), trim(varname)
  endif
  if (is_root_pe()) then
    if (cs%log_open) write(cs%stdlog,'(a)') trim(mesg)
    if (cs%log_to_stdout) write(cs%stdout,'(a)') trim(mesg)
  endif

  myunits="Boolean"; if (present(units)) write(myunits(1:240),'(A)') trim(units)
  if (present(desc)) &
    call doc_param(cs%doc, varname, desc, myunits, value, default, &
                   layoutparam=layoutparam)

end subroutine log_param_logical

subroutine log_param_char(CS, modulename, varname, value, desc, units, &
                          default, layoutParam)
  type(param_file_type),      intent(in) :: CS
  character(len=*),           intent(in) :: modulename
  character(len=*),           intent(in) :: varname
  character(len=*),           intent(in) :: value
  character(len=*), optional, intent(in) :: desc, units
  character(len=*), optional, intent(in) :: default
  logical,          optional, intent(in) :: layoutParam
! This subroutine writes the value of a character string parameter to a log
! file, along with its name and the module it came from.
  character(len=240) :: mesg, myunits

  write(mesg, '("  ",a," ",a,": ",a)') &
    trim(modulename), trim(varname), trim(value)
  if (is_root_pe()) then
    if (cs%log_open) write(cs%stdlog,'(a)') trim(mesg)
    if (cs%log_to_stdout) write(cs%stdout,'(a)') trim(mesg)
  endif

  myunits=" "; if (present(units)) write(myunits(1:240),'(A)') trim(units)
  if (present(desc)) &
    call doc_param(cs%doc, varname, desc, myunits, value, default, &
                   layoutparam=layoutparam)

end subroutine log_param_char

!> This subroutine writes the value of a time-type parameter to a log file,
!! along with its name and the module it came from.
subroutine log_param_time(CS, modulename, varname, value, desc, units, &
                          default, timeunit, layoutParam, log_date)
  type(param_file_type),      intent(in) :: CS
  character(len=*),           intent(in) :: modulename
  character(len=*),           intent(in) :: varname
  type(time_type),            intent(in) :: value
  character(len=*), optional, intent(in) :: desc, units
  type(time_type),  optional, intent(in) :: default
  real,             optional, intent(in) :: timeunit
  logical,          optional, intent(in) :: log_date   !< If true, log the time_type in date format.
  logical,          optional, intent(in) :: layoutParam

  real :: real_time, real_default
  logical :: use_timeunit, date_format
  character(len=240) :: mesg, myunits
  character(len=80) :: date_string, default_string
  integer :: days, secs, ticks, ticks_per_sec

  use_timeunit = .false.
  date_format = .false. ; if (present(log_date)) date_format = log_date

  call get_time(value, secs, days, ticks)

  if (ticks == 0) then
    write(mesg, '("  ",a," ",a," (Time): ",i0,":",i0)') trim(modulename), &
       trim(varname), days, secs
  else
    write(mesg, '("  ",a," ",a," (Time): ",i0,":",i0,":",i0)') trim(modulename), &
       trim(varname), days, secs, ticks
  endif
  if (is_root_pe()) then
    if (cs%log_open) write(cs%stdlog,'(a)') trim(mesg)
    if (cs%log_to_stdout) write(cs%stdout,'(a)') trim(mesg)
  endif

  if (present(desc)) then
    if (present(timeunit)) use_timeunit = (timeunit > 0.0)
    if (date_format) then
      myunits='[date]'

      date_string = convert_date_to_string(value)
      if (present(default)) then
        default_string = convert_date_to_string(default)
        call doc_param(cs%doc, varname, desc, myunits, date_string, &
                       default=default_string, layoutparam=layoutparam)
      else
        call doc_param(cs%doc, varname, desc, myunits, date_string, &
                       layoutparam=layoutparam)
      endif
    elseif (use_timeunit) then
      if (present(units)) then
        write(myunits(1:240),'(A)') trim(units)
      else
        if (abs(timeunit-1.0) < 0.01) then ; myunits = "seconds"
        elseif (abs(timeunit-3600.0) < 1.0) then ; myunits = "hours"
        elseif (abs(timeunit-86400.0) < 1.0) then ; myunits = "days"
        elseif (abs(timeunit-3.1e7) < 1.0e6) then ; myunits = "years"
        else ; write(myunits,'(es8.2," sec")') timeunit ; endif
      endif
      real_time = (86400.0/timeunit)*days + secs/timeunit
      if (ticks > 0) real_time = real_time + &
                           real(ticks) / (timeunit*get_ticks_per_second())
      if (present(default)) then
        call get_time(default, secs, days, ticks)
        real_default = (86400.0/timeunit)*days + secs/timeunit
        if (ticks > 0) real_default = real_default + &
                           real(ticks) / (timeunit*get_ticks_per_second())
        call doc_param(cs%doc, varname, desc, myunits, real_time, real_default)
      else
        call doc_param(cs%doc, varname, desc, myunits, real_time)
      endif
    else
      myunits='not defined'; if (present(units)) write(myunits(1:240),'(A)') trim(units)
      call doc_param(cs%doc, varname, desc, myunits, value, default)
    endif
  endif

end subroutine log_param_time

!> This function converts a date into a string, valid with ticks and for dates up to year 99,999,999
function convert_date_to_string(date) result(date_string)
  type(time_type), intent(in) :: date !< The date to be translated into a string.
  character(len=40) :: date_string    !< A date string in a format like YYYY-MM-DD HH:MM:SS.sss

  character(len=40) :: sub_string
  real    :: real_secs
  integer :: yrs, mons, days, hours, mins, secs, ticks, ticks_per_sec

  call get_date(date, yrs, mons, days, hours, mins, secs, ticks)
  write (date_string, '(i8.4)') yrs
  write (sub_string, '("-", i2.2, "-", I2.2, " ", i2.2, ":", i2.2, ":")') &
         mons, days, hours, mins
  date_string = trim(adjustl(date_string)) // trim(sub_string)
  if (ticks > 0) then
    ticks_per_sec = get_ticks_per_second()
    real_secs = secs + ticks/ticks_per_sec
    if (ticks_per_sec <= 100) then
      write (sub_string, '(F7.3)') real_secs
    else
      write (sub_string, '(F10.6)') real_secs
    endif
  else
    write (sub_string, '(i2.2)') secs
  endif
  date_string = trim(date_string) // trim(adjustl(sub_string))

end function convert_date_to_string

subroutine get_param_int(CS, modulename, varname, value, desc, units, &
               default, fail_if_missing, do_not_read, do_not_log, &
               static_value, layoutParam)
  type(param_file_type),      intent(in)    :: CS
  character(len=*),           intent(in)    :: modulename
  character(len=*),           intent(in)    :: varname
  integer,                    intent(inout) :: value
  character(len=*), optional, intent(in)    :: desc, units
  integer,          optional, intent(in)    :: default, static_value
  logical,          optional, intent(in)    :: fail_if_missing
  logical,          optional, intent(in)    :: do_not_read, do_not_log
  logical,          optional, intent(in)    :: layoutParam
! This subroutine writes the value of a real parameter to a log file,
! along with its name and the module it came from.
  logical :: do_read, do_log

  do_read = .true. ; if (present(do_not_read)) do_read = .not.do_not_read
  do_log  = .true. ; if (present(do_not_log))  do_log  = .not.do_not_log

  if (do_read) then
    if (present(default)) value = default
    if (present(static_value)) value = static_value
    call read_param_int(cs, varname, value, fail_if_missing)
  endif

  if (do_log) then
    call log_param_int(cs, modulename, varname, value, desc, units, &
                       default, layoutparam)
  endif

end subroutine get_param_int

subroutine get_param_int_array(CS, modulename, varname, value, desc, units, &
               default, fail_if_missing, do_not_read, do_not_log, &
               static_value, layoutParam)
  type(param_file_type),      intent(in)    :: CS
  character(len=*),           intent(in)    :: modulename
  character(len=*),           intent(in)    :: varname
  integer,                    intent(inout) :: value(:)
  character(len=*), optional, intent(in)    :: desc, units
  integer,          optional, intent(in)    :: default, static_value
  logical,          optional, intent(in)    :: fail_if_missing
  logical,          optional, intent(in)    :: do_not_read, do_not_log
  logical,          optional, intent(in)    :: layoutParam
! This subroutine writes the value of a real parameter to a log file,
! along with its name and the module it came from.
  logical :: do_read, do_log

  do_read = .true. ; if (present(do_not_read)) do_read = .not.do_not_read
  do_log  = .true. ; if (present(do_not_log))  do_log  = .not.do_not_log

  if (do_read) then
    if (present(default)) then ; value(:) = default ; endif
    if (present(static_value)) then ; value(:) = static_value ; endif
    call read_param_int_array(cs, varname, value, fail_if_missing)
  endif

  if (do_log) then
    call log_param_int_array(cs, modulename, varname, value, desc, &
                             units, default, layoutparam)
  endif

end subroutine get_param_int_array

subroutine get_param_real(CS, modulename, varname, value, desc, units, &
               default, fail_if_missing, do_not_read, do_not_log, static_value)
  type(param_file_type),      intent(in)    :: CS
  character(len=*),           intent(in)    :: modulename
  character(len=*),           intent(in)    :: varname
  real,                       intent(inout) :: value
  character(len=*), optional, intent(in)    :: desc, units
  real,             optional, intent(in)    :: default, static_value
  logical,          optional, intent(in)    :: fail_if_missing
  logical,          optional, intent(in)    :: do_not_read, do_not_log
! This subroutine writes the value of a real parameter to a log file,
! along with its name and the module it came from.
  logical :: do_read, do_log

  do_read = .true. ; if (present(do_not_read)) do_read = .not.do_not_read
  do_log  = .true. ; if (present(do_not_log))  do_log  = .not.do_not_log

  if (do_read) then
    if (present(default)) value = default
    if (present(static_value)) value = static_value
    call read_param_real(cs, varname, value, fail_if_missing)
  endif

  if (do_log) then
    call log_param_real(cs, modulename, varname, value, desc, units, &
                        default)
  endif

end subroutine get_param_real

subroutine get_param_real_array(CS, modulename, varname, value, desc, units, &
               default, fail_if_missing, do_not_read, do_not_log, static_value)
  type(param_file_type),      intent(in)    :: CS
  character(len=*),           intent(in)    :: modulename
  character(len=*),           intent(in)    :: varname
  real,                       intent(inout) :: value(:)
  character(len=*), optional, intent(in)    :: desc, units
  real,             optional, intent(in)    :: default, static_value
  logical,          optional, intent(in)    :: fail_if_missing
  logical,          optional, intent(in)    :: do_not_read, do_not_log
! This subroutine writes the value of a real parameter to a log file,
! along with its name and the module it came from.
  logical :: do_read, do_log

  do_read = .true. ; if (present(do_not_read)) do_read = .not.do_not_read
  do_log  = .true. ; if (present(do_not_log))  do_log  = .not.do_not_log

  if (do_read) then
    if (present(default)) then ; value(:) = default ; endif
    if (present(static_value)) then ; value(:) = static_value ; endif
    call read_param_real_array(cs, varname, value, fail_if_missing)
  endif

  if (do_log) then
    call log_param_real_array(cs, modulename, varname, value, desc, &
                              units, default)
  endif

end subroutine get_param_real_array

subroutine get_param_char(CS, modulename, varname, value, desc, units, &
               default, fail_if_missing, do_not_read, do_not_log, &
               static_value, layoutParam)
  type(param_file_type),      intent(in)    :: CS
  character(len=*),           intent(in)    :: modulename
  character(len=*),           intent(in)    :: varname
  character(len=*),           intent(inout) :: value
  character(len=*), optional, intent(in)    :: desc, units
  character(len=*), optional, intent(in)    :: default, static_value
  logical,          optional, intent(in)    :: fail_if_missing
  logical,          optional, intent(in)    :: do_not_read, do_not_log
  logical,          optional, intent(in)    :: layoutParam
! This subroutine writes the value of a real parameter to a log file,
! along with its name and the module it came from.
  logical :: do_read, do_log

  do_read = .true. ; if (present(do_not_read)) do_read = .not.do_not_read
  do_log  = .true. ; if (present(do_not_log))  do_log  = .not.do_not_log

  if (do_read) then
    if (present(default)) value = default
    if (present(static_value)) value = static_value
    call read_param_char(cs, varname, value, fail_if_missing)
  endif

  if (do_log) then
    call log_param_char(cs, modulename, varname, value, desc, units, &
                        default, layoutparam)
  endif

end subroutine get_param_char

subroutine get_param_char_array(CS, modulename, varname, value, desc, units, &
               default, fail_if_missing, do_not_read, do_not_log, static_value)
  type(param_file_type),      intent(in)    :: CS
  character(len=*),           intent(in)    :: modulename
  character(len=*),           intent(in)    :: varname
  character(len=*),           intent(inout) :: value(:)
  character(len=*), optional, intent(in)    :: desc, units
  character(len=*), optional, intent(in)    :: default, static_value
  logical,          optional, intent(in)    :: fail_if_missing
  logical,          optional, intent(in)    :: do_not_read, do_not_log
! This subroutine writes the value of a real parameter to a log file,
! along with its name and the module it came from.
  logical :: do_read, do_log
  integer :: i, len_tot, len_val
  character(len=240) :: cat_val

  do_read = .true. ; if (present(do_not_read)) do_read = .not.do_not_read
  do_log  = .true. ; if (present(do_not_log))  do_log  = .not.do_not_log

  if (do_read) then
    if (present(default)) then ; value(:) = default ; endif
    if (present(static_value)) then ; value(:) = static_value ; endif
    call read_param_char_array(cs, varname, value, fail_if_missing)
  endif

  if (do_log) then
    cat_val = trim(value(1)); len_tot = len_trim(value(1))
    do i=2,size(value)
      len_val = len_trim(value(i))
      if ((len_val > 0) .and. (len_tot + len_val + 2 < 240)) then
        cat_val = trim(cat_val)//achar(34)// ", "//achar(34)//trim(value(i))
        len_tot = len_tot + len_val
      endif
    enddo
    call log_param_char(cs, modulename, varname, cat_val, desc, &
                        units, default)
  endif

end subroutine get_param_char_array

subroutine get_param_logical(CS, modulename, varname, value, desc, units, &
               default, fail_if_missing, do_not_read, do_not_log, &
               static_value, layoutParam)
  type(param_file_type),      intent(in)    :: CS
  character(len=*),           intent(in)    :: modulename
  character(len=*),           intent(in)    :: varname
  logical,                    intent(inout) :: value
  character(len=*), optional, intent(in)    :: desc, units
  logical,          optional, intent(in)    :: default, static_value
  logical,          optional, intent(in)    :: fail_if_missing
  logical,          optional, intent(in)    :: do_not_read, do_not_log
  logical,          optional, intent(in)    :: layoutParam
! This subroutine writes the value of a real parameter to a log file,
! along with its name and the module it came from.
  logical :: do_read, do_log

  do_read = .true. ; if (present(do_not_read)) do_read = .not.do_not_read
  do_log  = .true. ; if (present(do_not_log))  do_log  = .not.do_not_log

  if (do_read) then
    if (present(default)) value = default
    if (present(static_value)) value = static_value
    call read_param_logical(cs, varname, value, fail_if_missing)
  endif

  if (do_log) then
    call log_param_logical(cs, modulename, varname, value, desc, &
                           units, default, layoutparam)
  endif

end subroutine get_param_logical

subroutine get_param_time(CS, modulename, varname, value, desc, units, &
                          default, fail_if_missing, do_not_read, do_not_log, &
                          timeunit, static_value, layoutParam, log_as_date)
  type(param_file_type),      intent(in)    :: CS
  character(len=*),           intent(in)    :: modulename
  character(len=*),           intent(in)    :: varname
  type(time_type),            intent(inout) :: value
  character(len=*), optional, intent(in)    :: desc, units
  type(time_type),  optional, intent(in)    :: default, static_value
  logical,          optional, intent(in)    :: fail_if_missing
  logical,          optional, intent(in)    :: do_not_read, do_not_log
  real,             optional, intent(in)    :: timeunit
  logical,          optional, intent(in)    :: layoutParam
  logical,          optional, intent(in)    :: log_as_date
! This subroutine writes the value of a real parameter to a log file,
! along with its name and the module it came from.
  logical :: do_read, do_log, date_format, log_date

  do_read = .true. ; if (present(do_not_read)) do_read = .not.do_not_read
  do_log  = .true. ; if (present(do_not_log))  do_log  = .not.do_not_log
  log_date = .false.

  if (do_read) then
    if (present(default)) value = default
    if (present(static_value)) value = static_value
    call read_param_time(cs, varname, value, timeunit, fail_if_missing, date_format=log_date)
  endif

  if (do_log) then
    if (present(log_as_date)) log_date = log_as_date
    call log_param_time(cs, modulename, varname, value, desc, units, default, &
                        timeunit, layoutparam=layoutparam, log_date=log_date)
  endif

end subroutine get_param_time

! -----------------------------------------------------------------------------

subroutine clearparameterblock(CS)
  type(param_file_type), intent(in) :: CS
! Resets the parameter block name to blank
  type(parameter_block), pointer :: block
  if (associated(cs%blockName)) then
    block => cs%blockName
    block%name = ''
  else
    if (is_root_pe()) call mom_error(fatal, &
      'clearParameterBlock: A clear was attempted before allocation.')
  endif
end subroutine clearparameterblock

subroutine openparameterblock(CS,blockName,desc)
  type(param_file_type),      intent(in) :: CS
  character(len=*),           intent(in) :: blockName
  character(len=*), optional, intent(in) :: desc
! Tags blockName onto the end of the active parameter block name
  type(parameter_block), pointer :: block
  if (associated(cs%blockName)) then
    block => cs%blockName
    block%name = pushblocklevel(block%name,blockname)
    call doc_openblock(cs%doc,block%name,desc)
  else
    if (is_root_pe()) call mom_error(fatal, &
      'openParameterBlock: A push was attempted before allocation.')
  endif
end subroutine openparameterblock

subroutine closeparameterblock(CS)
  type(param_file_type), intent(in) :: CS
! Remove the lowest level of recursion from the active block name
  type(parameter_block), pointer :: block

  if (associated(cs%blockName)) then
    block => cs%blockName
    if (is_root_pe().and.len_trim(block%name)==0) call mom_error(fatal, &
      'closeParameterBlock: A pop was attempted on an empty stack. ("'//&
      trim(block%name)//'")')
    call doc_closeblock(cs%doc,block%name)
  else
    if (is_root_pe()) call mom_error(fatal, &
      'closeParameterBlock: A pop was attempted before allocation.')
  endif
  block%name = popblocklevel(block%name)
end subroutine closeparameterblock

function pushblocklevel(oldblockName,newBlockName)
  character(len=*),        intent(in) :: oldBlockName, newBlockName
  character(len=len(oldBlockName)+40) :: pushBlockLevel
! Extends block name (deeper level of parameter block)
  if (len_trim(oldblockname)>0) then
    pushblocklevel=trim(oldblockname)//'%'//trim(newblockname)
  else
    pushblocklevel=trim(newblockname)
  endif
end function pushblocklevel

function popblocklevel(oldblockName)
  character(len=*),        intent(in) :: oldBlockName
  character(len=len(oldBlockName)+40) :: popBlockLevel
! Truncates block name (shallower level of parameter block)
  integer :: i
  i = index(trim(oldblockname), '%', .true.)
  if (i>1) then
    popblocklevel = trim(oldblockname(1:i-1))
  elseif (i==0) then
    popblocklevel = ''
  else ! i==1
    if (is_root_pe()) call mom_error(fatal, &
      'popBlockLevel: A pop was attempted leaving an empty block name.')
  endif
end function popblocklevel

end module mom_file_parser