!-----------------------------------------------------------------------------
!
! getnc_dims -- Get sizes of standard named dimensions from Netcdf file.
!
! For use with netopen and/or netcdf API.
!
! 2005-dec-13	Early version.  By Dave Allured.
!		Assumes fixed coordinate variable names and other assumptions.
!		ntimes and nlevels are stubs only.
! 2008-nov-05	Add support for ntimes, nlevels.
!		Add module interface.
!		Improve diagnostics.
! 2008-nov-11	Change module names to double underscore.
! 2010-feb-19	Switch to standard visibility controls.
!		Use netcdf__check module.
!
! Usage:
!
! 1.  Open a netcdf file with netopen, nf90_open, etc.
!
! 2.  Call getnc_dims to get the dimension sizes.
!
! Notes:
!
! Any dimension size returned as 0 means that the dimension is
! absent.  Exception:  Zero may also indicate a zero-length
! record dimension, which also indicates an empty data variable.
!
! ntimes returns the current number of time steps, whether or not
! the time dimension is unlimited.
!
!-----------------------------------------------------------------------------


module getnc__dims
   private				! visibility controls
   public getnc_dims

contains


!-----------------------------------------------------------------------------
! getnc_one_dim -- Private routine for getnc_dims.  Get size for 1 dimension.
!-----------------------------------------------------------------------------

function getnc_one_dim (ncid, varname) result (dim_size)

   use netcdf
   use netcdf__check
   implicit none
   
   integer,      intent (in) :: ncid		! netcdf file ID number
   character(*), intent (in) :: varname		! fixed dimension name
   
   integer :: dim_size				! result var: output dim size

! Local variables.

   integer status, varid, ndims, dimid(1)

! Check for coordinate variable matching the requested dimension name.

   status = nf90_inq_varid (ncid, varname, varid)   ! get coordinate var ID
   
   if (status == nf90_enotvar) then		! if missing coordinate var:
      dim_size = 0				! return zero size as signal
      return					! for missing dimension
   end if

   if (status /= nf90_noerr) then	! other Netcdf error: report fatal error
      print *, '*** Fatal: getnc_dims: Netcdf error reading coordinate var "' &
         // trim (varname) // '"'
      call check (status)			! report error details and abort
      stop 99					! check should never return here
   end if

! Found coordinate variable.  Get dimension ID and dim size.
   
   call check (nf90_inquire_variable (ncid, varid, ndims=ndims))
						! check rank to be safe

   if (ndims /= 1) then
      print *, '*** Fatal: getnc_dims: Coordinate var "' // trim (varname) &
         // '" is not 1-dimensional in netcdf file.'
      write (*, '(a, i0)') ' *** Number of dimensions = ', ndims
      call exit (1)
   end if

   call check (nf90_inquire_variable (ncid, varid, dimids=dimid))   ! get dim ID
   call check (nf90_inquire_dimension (ncid, dimid(1), len=dim_size)) ! get size

end function getnc_one_dim


!-----------------------------------------------------------------------------
! getnc_dims -- Main subroutine.  Get sizes of four Netcdf named dimensions.
!-----------------------------------------------------------------------------

subroutine getnc_dims (ncid, nx, ny, ntimes, nlevels)
   implicit none
   
   integer, intent (in ) :: ncid		! netcdf file ID number
   integer, intent (out) :: nx			! size of X dim (longitude)
   integer, intent (out) :: ny			! size of Y dim (latitude)
   integer, intent (out) :: ntimes		! size of time dimension
   integer, intent (out) :: nlevels		! size of level dimension

! Look up coordinate var and dim size for each fixed dimension name.
   
   nx      = getnc_one_dim (ncid, "lon")
   ny      = getnc_one_dim (ncid, "lat")
   ntimes  = getnc_one_dim (ncid, "time")
   nlevels = getnc_one_dim (ncid, "level")

end subroutine getnc_dims

end module getnc__dims