ESMF_CFIOUtilMod Module

MODULE: ESMF_CFIOUtilMod

Author: GMAO SI-Team

ESMF_CFIOUtilMod - utility subroutines for CFIO

The module ESMF_CFIOUtilMod provides all the necessary utility subroutines for CFIO.

History

  • Sep2004 Baoyu Yin Modified from ESMF_CFIOMod.F90.
  • Mar2005 Baoyu Yin Integrated all routines of GFIO into CFIO.
  • Apr2005 Baoyu Yin Added Get_Missing routine
  • Apr2006 da Silva Incorporated m_StrTemplate to eliminate mpeu dependency.
  • Jun2006 Baoyu yin Added cyclic option to GetVar.
  • Jul2006 da Silva Eliminated read(str,fmt) to parse time; replaced with more robust mod() calculations.

Uses

  • module~~esmf_cfioutilmod~~UsesGraph module~esmf_cfioutilmod ESMF_CFIOUtilMod ESMF_CFIOBaseMod ESMF_CFIOBaseMod module~esmf_cfioutilmod->ESMF_CFIOBaseMod iso_fortran_env iso_fortran_env module~esmf_cfioutilmod->iso_fortran_env netcdf netcdf module~esmf_cfioutilmod->netcdf

Used by

  • module~~esmf_cfioutilmod~~UsedByGraph module~esmf_cfioutilmod ESMF_CFIOUtilMod module~esmf_cfiocollectionmod ESMF_CFIOCollectionMod module~esmf_cfiocollectionmod->module~esmf_cfioutilmod module~esmf_cfioeosmod ESMF_CFIOEosMod module~esmf_cfioeosmod->module~esmf_cfioutilmod module~esmf_cfiofilemod ESMF_CFIOFileMod module~esmf_cfiofilemod->module~esmf_cfioutilmod module~esmf_cfiogridmod ESMF_CFIOGridMod module~esmf_cfiogridmod->module~esmf_cfioutilmod module~esmf_cfiomod ESMF_CFIOMod module~esmf_cfiomod->module~esmf_cfioutilmod module~esmf_cfiosdfmod ESMF_CFIOSdfMod module~esmf_cfiosdfmod->module~esmf_cfioutilmod module~esmf_cfiovarinfomod ESMF_CFIOVarInfoMod module~esmf_cfiovarinfomod->module~esmf_cfioutilmod module~mapl_cfiomod MAPL_CFIOMod module~mapl_cfiomod->module~esmf_cfioutilmod module~mapl_extdatagridcompmod MAPL_ExtDataGridCompMod module~mapl_extdatagridcompmod->module~esmf_cfioutilmod program~regrid_util Regrid_Util program~regrid_util->module~esmf_cfioutilmod

Variables

Type Visibility Attributes Name Initial
character(len=*), public, parameter :: myname = 'm_StrTemplate'
character(len=3), public, parameter, dimension(12) :: mon_lc = (/'jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'/)
character(len=3), public, parameter, dimension(12) :: mon_uc = (/'JAN', 'FEB', 'MAR', 'APR', 'MAY', 'JUN', 'JUL', 'AUG', 'SEP', 'OCT', 'NOV', 'DEC'/)
character(len=3), public, parameter, dimension(12) :: mon_wd = (/'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'/)
character(len=7), public, parameter :: GRID_NAME = 'EOSGRID'
integer, public, parameter :: GCTP_GEO = 0
integer, public, parameter :: HDFE_GD_LL = 2
integer, public, parameter :: HDFE_NOMERGE = 0
integer, public, parameter :: MAXCHR = 256
integer, public, parameter :: MAX_VAR_DIMS = 32
integer, public, parameter :: MLEN = 1024
integer, public, parameter :: MVARLEN = 256
integer, public, parameter :: NDIMS_MAX = 4
integer, public, parameter :: PACK_BITS = 32766
integer, public, parameter :: PACK_FILL = 32767
integer, public, parameter :: stderr = 6

Interfaces

public interface GetDate

  • public subroutine GetDateInt8(yyyymmdd_1, hhmmss_1, offset, yyyymmdd_2, hhmmss_2, rc)

    GetDateInt8 — Returns a new date/time from an initial date/time and offset

    This subroutine returns a new date and time in yyyymmdd and hhmmss format given and initial date, time, and offset in seconds. The routine converts the input date and time to julian seconds, adds the offset, and converts back to yyyymmdd and hhmmss format. This routine has been tested for Y2K compiance.

    History

    • 1998.07.20 Lucchesi Initial version.
    • 2010.05.11 Lucchesi Integer for julian seconds changed to 64-bit. StartDate constant no longer needed.

    Arguments

    Type IntentOptional Attributes Name
    integer :: yyyymmdd_1

    Initial date in YYYYYMMDD format
    integer :: hhmmss_1

    Initial time in HHMMSS format
    integer(kind=INT64) :: offset

    Offset to add (in seconds)
    integer :: yyyymmdd_2

    New date in YYYYMMDD format
    integer :: hhmmss_2

    New time in HHMMSS format
    integer :: rc

    Return code. (<0 = error)

  • public subroutine GetDateInt4(yyyymmdd_1, hhmmss_1, offset, yyyymmdd_2, hhmmss_2, rc)

    GetDateInt4 — Returns a new date/time from an initial date/time and offset

    This subroutine returns a new date and time in yyyymmdd and hhmmss format given and initial date, time, and offset in seconds. The routine converts the input date and time to julian seconds, adds the offset, and converts back to yyyymmdd and hhmmss format. This routine has been tested for Y2K compiance.

    History

    • 1998.07.20 Lucchesi Initial version.
    • 2010.05.11 Lucchesi Integer for julian seconds changed to 64-bit. StartDate constant no longer needed.

    Arguments

    Type IntentOptional Attributes Name
    integer :: yyyymmdd_1

    Initial date in YYYYYMMDD format
    integer :: hhmmss_1

    Initial time in HHMMSS format
    integer :: offset

    Offset to add (in seconds)
    integer :: yyyymmdd_2

    New date in YYYYMMDD format
    integer :: hhmmss_2

    New time in HHMMSS format
    integer :: rc

    Return code. (<0 = error)

Derived Types

type, public ::  cNode

Components

Type Visibility Attributes Name Initial
character(len=MLEN), public :: charData
character(len=MVARLEN), public :: name
character(len=MVARLEN), public :: vName
integer, public :: count
type(cNode), public, pointer :: next => null()

type, public ::  iNode

Components

Type Visibility Attributes Name Initial
character(len=MVARLEN), public :: name
character(len=MVARLEN), public :: vName
integer, public :: count
integer, public, pointer :: intData(:)
type(iNode), public, pointer :: next => null()

type, public ::  rNode

Components

Type Visibility Attributes Name Initial
character(len=MVARLEN), public :: name
character(len=MVARLEN), public :: vName
integer, public :: count
real, public, pointer :: realData(:)
type(rNode), public, pointer :: next => null()

Functions

public function IdentifyDim(dimName, dimUnits)

IdentifyDim - Identify a cooridate variable

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*) :: dimName

Name of the coordinate variable
character(len=*) :: dimUnits

Units of the coordinate variable

Return Value integer

public function err(outstring, iret, ec)

Arguments

Type IntentOptional Attributes Name
character(len=*) :: outstring
integer :: iret
integer :: ec

Return Value integer

public function DiffDate(yyyymmhh_1, hhmmss_1, yyyymmhh_2, hhmmss_2)

DiffDate — Calculates the number of seconds between two times.

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: yyyymmhh_1
integer :: hhmmss_1
integer :: yyyymmhh_2
integer :: hhmmss_2

Return Value integer(kind=int64)

public function julday(mm, id, iyyy)

Arguments

Type IntentOptional Attributes Name
integer :: mm
integer :: id
integer :: iyyy

Return Value integer

public function CFIO_GetMissing(fid, rc)

Arguments

Type IntentOptional Attributes Name
integer :: fid
integer :: rc

Return Value real


Subroutines

public subroutine CALDAT(JULIAN, MM, ID, IYYY)

Arguments

Type IntentOptional Attributes Name
integer(kind=INT64) :: JULIAN
integer :: MM
integer :: ID
integer :: IYYY

public subroutine CFIO_AttInquire(fid, name, type, count, rc)

CFIO_AttInquire – Get information about an attribute

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: fid

File handle
character(len=*) :: name

Name of attribute
integer :: type

Code for attribute type 0 = integer 1 = real 2 = character 3 = 64-bit real 4 = 64-bit integer -1 = other
integer :: count

Number of items (length of array)
integer :: rc

Error return code: rc = 0 all is well

Read more…

public subroutine CFIO_Close(fid, rc)

CFIO_Close – Closes file

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: fid

File handle
integer :: rc

Error return code: rc = 0 all is well

Read more…

public subroutine CFIO_DimInquire(fid, im, jm, km, lm, nvars, ngatts, vdir, rc)

CFIO_DimInquire – Gets dimension information from a CFIO file.

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: fid
integer :: im

Size of longitudinal dimension
integer :: jm

Size of latitudinal dimension
integer :: km

Size of vertical dimension km=0 if surface-only file
integer :: lm

Number of times
integer :: nvars

Number of variables
integer :: ngatts

Number of global attributes
integer, optional :: vdir

Positive vertical direction. If -1, level 1 in the file is TOA. If 1, level 1 in the file is the surface. If 0, the file has no vertical co-ordinate (default).
integer, optional :: rc

Error return code: rc = 0 all is well rc = -19 unable to identify coordinate variable

Read more…

public subroutine CFIO_GetAttNames(fid, ngatts, aname, rc)

CFIO_GetAttNames – Get global attribute names

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: fid

File handle
integer :: ngatts

Expected number of attributes (input) Actual number of attributes (output if rc=-2)
character(len=*) :: aname(ngatts)

Array of attribute names
integer :: rc

Error return code: rc = 0 all is well rc = -10 ngatts is incompatible with file rc = -11 character string not long enough

Read more…

public subroutine CFIO_GetCharAtt(fid, name, count, buf, rc)

CFIO_GetCharAtt – Read a user-defined character attribute

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: fid

File handle
character(len=*) :: name

Name of attribute
integer :: count

On input: Number of items in attribute On output: If rc = -1, count will contain the correct number of attributes
character(len=1) :: buf(count)

Buffer with character values
integer :: rc

Error return code: rc = 0 all is well rc = -1 invalid count rc = -2 type mismatch

Read more…

public subroutine CFIO_GetIntAtt(fid, name, count, buf, rc)

CFIO_GetIntAtt – Read a user-defined integer attribute

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: fid

File handle
character(len=*) :: name

Name of attribute
integer :: count

On input: Number of items in attribute On output: If rc = -1, count will contain the correct count of this attribute
integer :: buf(count)

Buffer with integer values
integer :: rc

Error return code: rc = 0 all is well rc = -1 invalid count rc = -2 type mismatch rc = -12 error determining default precision

Read more…

public subroutine CFIO_GetRealAtt(fid, name, count, buf, rc)

CFIO_GetRealAtt – Read a user-defined real attribute

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: fid

File handle
character(len=*) :: name

Name of attribute
integer :: count

On input: Number of items in attribute On output: If rc = -1, count will contain the correct number of attributes
real :: buf(count)

Buffer with real values
integer :: rc

Error return code: rc = 0 all is well rc = -1 invalid count rc = -2 type mismatch rc = -12 error determining default precision

Read more…

public subroutine CFIO_GetVar(fid, vname, yyyymmdd, hhmmss, im, jm, kbeg, kount, lm, grid, cyclic, useFaceDim, rc)

CFIO_GetVar – Read a variable from the file

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: fid

File handle
character(len=*) :: vname

Variable name
integer :: yyyymmdd

Year-month-day, e.g., 19971003
integer :: hhmmss

Hour-minute-second, e.g., 120000
integer :: im

size of longitudinal dimension
integer :: jm

size of latitudinal dimension
integer :: kbeg

first level to read; if 2-D grid set kbeg = 0.
integer :: kount

number of levels to read
integer :: lm

number of time steps
real :: grid(im,jm,kount)

Gridded data read for this time
logical :: cyclic

input file is cyclic or not
logical :: useFaceDim
integer :: rc

Error return code: rc = 0 all is well rc = -2 time is inconsistent with increment rc = -3 number of levels is incompatible with file rc = -4 im is incompatible with file rc = -5 jm is incompatible with file rc = -6 time must fall on a minute boundary rc = -7 error in diffdate rc = -12 error determining default precision rc = -13 error determining variable type rc = -19 unable to identify coordinate variable

Read more…

public subroutine CFIO_Open(fname, fmode, fid, rc)

CFIO_Open – Opens an existing DAO gridded file

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*) :: fname

File name
integer :: fmode

File mode: 0 for READ-WRITE non-zero for READ-ONLY
integer :: fid

File handle
integer :: rc

Error return code: rc = 0 All is well rc = -39 error from ncopn (file open)

public subroutine CFIO_PutCharAtt(fid, name, count, buf, rc)

CFIO_PutCharAtt – Write a user-defined character attribute

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: fid

File handle
character(len=*) :: name

Name of attribute
integer :: count

Number of characters to write
character(len=MLEN) :: buf

Buffer containing string
integer :: rc

Error return code: rc = 0 all is well

Read more…

public subroutine CFIO_PutIntAtt(fid, name, count, buf, prec, rc)

CFIO_PutIntAtt – Write a user-defined integer attribute

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: fid

File handle
character(len=*) :: name

Name of attribute
integer :: count

Number of integers to write
integer :: buf(count)

Buffer with integer values
integer :: prec

Desired precision of attribute value: 0 = 32 bit 1 = 64 bit
integer :: rc

Error return code: rc = 0 all is well rc = -12 error determining default precision

Read more…

public subroutine CFIO_PutRealAtt(fid, name, count, buf, prec, rc)

CFIO_PutRealAtt – Write a user-defined real attribute

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: fid

File handle
character(len=*) :: name

Name of attribute
integer :: count

Number of integers to write
real :: buf(count)

Buffer with real values
integer :: prec

Desired precision of attribute value: 0 = 32 bit 1 = 64 bit
integer :: rc

Error return code: rc = 0 all is well rc = -12 error determining default precision

Read more…

public subroutine CFIO_PutVar(fid, vname, yyyymmdd, hhmmss, im, jm, kbeg, kount, grid, useFaceDim, rc)

CFIO_PutVar – Write a variable to the file

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: fid

File handle
character(len=*) :: vname

Variable name
integer :: yyyymmdd

Year-month-day, e.g., 19971003
integer :: hhmmss

Hour-minute-second, e.g., 120000
integer :: im

size of longitudinal dimension
integer :: jm

size of latitudinal dimension
integer :: kbeg

first level to write; if 2-D grid use kbeg = 0.
integer :: kount

number of levels to write
real :: grid(im,jm,kount)

Gridded data to write at this time
logical :: useFaceDim
integer :: rc

Error return code: rc = 0 all is well rc = -2 time is inconsistent with increment rc = -3 number of levels is incompatible with file rc = -4 im is incompatible with file rc = -5 jm is incompatible with file rc = -6 time must fall on a minute boundary rc = -7 error in diffdate rc = -12 error determining default precision rc = -13 error determining variable type rc = -15 data outside of valid range rc = -16 data outside of packing range rc = -17 data outside of pack and valid range

Read more…

public subroutine CFIO_SGetVar(fid, vname, yyyymmdd, hhmmss, im, jm, kbeg, kount, lm, grid, cyclic, rc)

CFIO_SGetVar – Read a variable from the file

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: fid

File handle
character(len=*) :: vname

Variable name
integer :: yyyymmdd

Year-month-day, e.g., 19971003
integer :: hhmmss

Hour-minute-second, e.g., 120000
integer :: im

size of longitudinal dimension
integer :: jm

size of latitudinal dimension
integer :: kbeg

first level to read; if 2-D grid set kbeg = 0.
integer :: kount

number of levels to read
integer :: lm

number of time steps
real :: grid(im,kount)

Gridded data read for this time
logical :: cyclic

input file is cyclic or not
integer :: rc

Error return code: rc = 0 all is well rc = -2 time is inconsistent with increment rc = -3 number of levels is incompatible with file rc = -4 im is incompatible with file rc = -5 jm is incompatible with file rc = -6 time must fall on a minute boundary rc = -7 error in diffdate rc = -12 error determining default precision rc = -13 error determining variable type rc = -19 unable to identify coordinate variable

Read more…

public subroutine CFIO_SPutVar(fid, vname, yyyymmdd, hhmmss, im, jm, kbeg, kount, grid, rc)

CFIO_SPutVar – Write a variable to the file

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: fid

File handle
character(len=*) :: vname

Variable name
integer :: yyyymmdd

Year-month-day, e.g., 19971003
integer :: hhmmss

Hour-minute-second, e.g., 120000
integer :: im

size of longitudinal dimension
integer :: jm

size of latitudinal dimension
integer :: kbeg

first level to write; if 2-D grid use kbeg = 0.
integer :: kount

number of levels to write
real :: grid(im,kount)

Gridded data to write at this time
integer :: rc

Error return code: rc = 0 all is well rc = -2 time is inconsistent with increment rc = -3 number of levels is incompatible with file rc = -4 im is incompatible with file rc = -5 jm is incompatible with file rc = -6 time must fall on a minute boundary rc = -7 error in diffdate rc = -12 error determining default precision rc = -13 error determining variable type rc = -15 data outside of valid range rc = -16 data outside of packing range rc = -17 data outside of pack and valid range

Read more…

public subroutine CFIO_parseIntTime(hhmmss, hour, min, sec)

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: hhmmss
integer, intent(out) :: hour
integer, intent(out) :: min
integer, intent(out) :: sec

public subroutine GX_(str, tmpl, xid, nymd, nhms, stat)

GX_ - evaluate a GrADS style string template

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(out) :: str
character(len=*), intent(in) :: tmpl
character(len=*), intent(in), optional :: xid
integer, intent(in), optional :: nymd
integer, intent(in), optional :: nhms
integer, intent(out), optional :: stat

public subroutine GetBegDateTime(fid, begDate, begTime, incSecs, rc)

GetBegDateTime - Get begin date/time of file

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: fid

file ID
integer :: begDate

beginning date
integer :: begTime

beginning time
integer :: incSecs

time increment in secs
integer :: rc

error return code

public subroutine GetDateInt4(yyyymmdd_1, hhmmss_1, offset, yyyymmdd_2, hhmmss_2, rc)

GetDateInt4 — Returns a new date/time from an initial date/time and offset

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: yyyymmdd_1

Initial date in YYYYYMMDD format
integer :: hhmmss_1

Initial time in HHMMSS format
integer :: offset

Offset to add (in seconds)
integer :: yyyymmdd_2

New date in YYYYMMDD format
integer :: hhmmss_2

New time in HHMMSS format
integer :: rc

Return code. (<0 = error)

public subroutine GetDateInt8(yyyymmdd_1, hhmmss_1, offset, yyyymmdd_2, hhmmss_2, rc)

GetDateInt8 — Returns a new date/time from an initial date/time and offset

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: yyyymmdd_1

Initial date in YYYYYMMDD format
integer :: hhmmss_1

Initial time in HHMMSS format
integer(kind=INT64) :: offset

Offset to add (in seconds)
integer :: yyyymmdd_2

New date in YYYYMMDD format
integer :: hhmmss_2

New time in HHMMSS format
integer :: rc

Return code. (<0 = error)

public subroutine GetDateTimeVec(fid, begDate, begTime, incVec, rc)

GetDateTimeVec - Get date/time of file samples

Read more…

Arguments

Type IntentOptional Attributes Name
integer :: fid

file ID
integer :: begDate

Beginning date
integer :: begTime

Beginning time
integer(kind=INT64) :: incVec(:)

Vector of offsets (seconds)
integer :: rc

error return code

public subroutine ParseTimeUnits(TimeUnits, year, month, day, hour, min, sec, rc)

ParseTimeUnits – Parse the COARDS time units string

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=MAXCHR) :: TimeUnits

Units metadata string from the Time coord var
integer :: year

4-digit year
integer :: month

month
integer :: day

day
integer :: hour

hour
integer :: min

minute
integer :: sec

second
integer :: rc

return code 0 = no error -1 = problem parsing string

public subroutine addList(name, count, vName, attInt, attChar, attReal, iList, rList, cList)

addList – put user defined attribute into a list.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: name
integer, intent(in) :: count
character(len=*), intent(in), optional :: vName
integer, intent(in), optional :: attInt(*)
character(len=MLEN), intent(in), optional :: attChar
real, intent(in), optional :: attReal(*)
type(iNode), optional, pointer :: iList

int list
type(rNode), optional, pointer :: rList

real list
type(cNode), optional, pointer :: cList

char list

public subroutine getList(iList, nIntAtt, intAttNames, intAttCnts, intAtts, rList, nRealAtt, realAttNames, realAttCnts, realAtts, cList, nCharAtt, charAttNames, charAttCnts, charAtts, vNames)

getList – retrieve defined attributes from a list

Arguments

Type IntentOptional Attributes Name
type(iNode), optional, pointer :: iList

int list
integer, optional :: nIntAtt

num of int att
character(len=MLEN), optional, pointer :: intAttNames(:)
integer, optional, pointer :: intAttCnts(:)

data count in int att
integer, optional, pointer :: intAtts(:,:)

int attribute
type(rNode), optional, pointer :: rList

char list
integer, optional :: nRealAtt

num of real att
character(len=MLEN), optional, pointer :: realAttNames(:)
integer, optional, pointer :: realAttCnts(:)

data count in real att
real, optional, pointer :: realAtts(:,:)

real attribute
type(cNode), optional, pointer :: cList

real list
integer, optional :: nCharAtt

num of char att
character(len=MLEN), optional, pointer :: charAttNames(:)
integer, optional, pointer :: charAttCnts(:)

data count in char att
character(len=MLEN), optional, pointer :: charAtts(:)

char att
character(len=MLEN), optional, pointer :: vNames(:)

public subroutine getMaxLenCnt(maxLen, count, iList, rList, cList)

getMaxLenCnt – get length of a list and max number of data in the nodes

Read more…

Arguments

Type IntentOptional Attributes Name
integer, intent(out) :: maxLen
integer, intent(out) :: count
type(iNode), optional, pointer :: iList
type(rNode), optional, pointer :: rList
type(cNode), optional, pointer :: cList

public subroutine strTemplate_(str, tmpl, class, xid, nymd, nhms, stat)

strTemplate_ - expanding a format template to a string

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(out) :: str
character(len=*), intent(in) :: tmpl
character(len=*), intent(in), optional :: class
character(len=*), intent(in), optional :: xid
integer, intent(in), optional :: nymd
integer, intent(in), optional :: nhms
integer, intent(out), optional :: stat

public subroutine strToInt(timeString, date, begTime)

strToInt - convert timeString to integer date and time

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: timeString

string expression of data and time
integer, intent(out) :: date
integer, intent(out) :: begTime