ESMF_FieldRead Subroutine

  subroutine ESMF_FieldRead(field, fileName, keywordEnforcer,        &
      variableName, timeslice, iofmt, rc)
!
!
! !ARGUMENTS:
    type(ESMF_Field),      intent(inout)          :: field
    character(*),          intent(in)             :: fileName
type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
    character(*),          intent(in),  optional  :: variableName
    integer,               intent(in),  optional  :: timeslice
    type(ESMF_IOFmt_Flag), intent(in),  optional  :: iofmt
    integer,               intent(out), optional  :: rc
!
! !DESCRIPTION:
!   Read Field data from a file and put it into an {ESMF\_Field} object.
!   For this API to be functional, the environment variable {\tt ESMF\_PIO}
!   should be set to either "internal" or "external" when the ESMF library is built.
!   Please see the section on Data I/O,~\ref{io:dataio}.
!
!   Limitations:
!   \begin{itemize}
!     \item Not supported in {\tt ESMF\_COMM=mpiuni} mode.
!   \end{itemize}
!
!   The arguments are:
!   \begin{description}
!   \item [field]
!     The {\tt ESMF\_Field} object in which the read data is returned.
!   \item[fileName]
!     The name of the file from which Field data is read.
!     If the Field is a multi-tile Array, then fileName must contain
!     exactly one instance of "*"; this is a placeholder that will be replaced
!     by the tile number, with each tile being read from a separate file. (For
!     example, for a fileName of "myfile*.nc", tile 1 will be read from
!     "myfile1.nc", tile 2 from "myfile2.nc", etc.)
!     (This handling of the fileName for multi-tile I/O is subject to change.)
!   \item[{[variableName]}]
!    Variable name in the file; default is the "name" of Field.
!    Use this argument only in the I/O format (such as NetCDF) that
!    supports variable name. If the I/O format does not support this
!    (such as binary format), ESMF will return an error code.
!   \item[{[timeslice]}]
!     Number of slices to be read from file, starting from the 1st slice
!   \item[{[iofmt]}]
!     \begin{sloppypar}
!    The I/O format.  Please see Section~\ref{opt:iofmtflag} for the list
!    of options. If not present, defaults to {\tt ESMF\_IOFMT\_NETCDF}.
!     \end{sloppypar}
!   \item [{[rc]}]
!     Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
!   \end{description}
!
!EOP
    character(len=ESMF_MAXSTR)      :: name
    type(ESMF_FieldType), pointer   :: fp
    type(ESMF_Array)                :: array
    integer                         :: localrc
    type(ESMF_FieldStatus_Flag)     :: fieldstatus  ! Field's status
    type(ESMF_IOFmt_Flag)           :: opt_iofmt
    type(ESMF_IO)                   :: io           ! The I/O object
    integer                         :: file_ext_p
    logical                         :: errorFound   ! True if error condition
    integer                         :: time

#ifdef ESMF_PIO
!   Initialize
    localrc = ESMF_RC_NOT_IMPL
    if (present(rc)) rc = ESMF_RC_NOT_IMPL

    ! check variables
    ESMF_INIT_CHECK_DEEP(ESMF_FieldGetInit,field,rc)

    time = 0
    if(present(timeslice)) time = timeslice

    ! Set iofmt based on file name extension (if present)
    if (present (iofmt)) then
      opt_iofmt = iofmt
    else
      opt_iofmt = ESMF_IOFMT_NETCDF
    end if

    if (present(variableName)) then
      name = variableName
    else
      fp => field%ftypep

      call ESMF_GetName(fp%base, name, localrc)
      if (ESMF_LogFoundError(localrc, &
           ESMF_ERR_PASSTHRU, &
           ESMF_CONTEXT, rcToReturn=rc)) return
    endif

    call ESMF_FieldGet(field, array=array, rc=localrc)
    if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
        ESMF_CONTEXT, rcToReturn=rc)) return

    ! Create an I/O object
    io = ESMF_IOCreate(rc=localrc)
    if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU,              &
        ESMF_CONTEXT, rcToReturn=rc)) return

    ! From here on out, we need to clean up so no returning on error
    if (localrc .eq. ESMF_SUCCESS) then
      call ESMF_IOAddArray(io, array, variableName=name, rc=localrc)
      errorFound = ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU,   &
          ESMF_CONTEXT, rcToReturn=rc)
    endif

    if (.not. errorfound) then
      call ESMF_IORead(io, trim(fileName), timeslice=time,              &
          iofmt=opt_iofmt, rc=localrc)
      errorFound = ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU,   &
          ESMF_CONTEXT, rcToReturn=rc)
    endif

    ! Set rc here in case we had an error but destroy succeeds
    if (present(rc)) rc = localrc

    call ESMF_IODestroy(io, rc=localrc)
    ! Log error but don't reset rc
    errorFound = ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU,     &
        ESMF_CONTEXT, rcToReturn=localrc)

    ! Last chance to return an error code (IODestroy failed)
    if (present(rc)) then
       if (rc .eq. ESMF_SUCCESS) rc = localrc
    end if

#else
    ! Return indicating PIO not present
    if (present(rc)) rc = ESMF_RC_LIB_NOT_PRESENT
#endif

  end subroutine ESMF_FieldRead