subroutine ESMF_ArrayBundleRead(arraybundle, fileName, keywordEnforcer, &
singleFile, timeslice, iofmt, rc)
!
! !ARGUMENTS:
type(ESMF_ArrayBundle), intent(inout) :: arraybundle
character(*), intent(in) :: fileName
type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
logical, intent(in), optional :: singleFile
integer, intent(in), optional :: timeslice
type(ESMF_IOFmt_Flag), intent(in), optional :: iofmt
integer, intent(out), optional :: rc
!
! !DESCRIPTION:
! Read Array data to an ArrayBundle object from file(s).
! 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 For multi-tile Arrays, all Arrays in the ArrayBundle must contain
! the same number of tiles.
! \item Not supported in {\tt ESMF\_COMM=mpiuni} mode.
! \end{itemize}
!
! The arguments are:
! \begin{description}
! \item[arraybundle]
! An {\tt ESMF\_ArrayBundle} object.
! \item[fileName]
! The name of the file from which ArrayBundle data is read.
! If the ArrayBundle contains multi-tile Arrays, 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[{[singleFile]}]
! A logical flag, the default is .true., i.e., all Arrays in the bundle
! are stored in one single file. If .false., each Array is stored
! in separate files; these files are numbered with the name based on the
! argument "file". That is, a set of files are named: [file\_name]001,
! [file\_name]002, [file\_name]003,...
! \item[{[timeslice]}]
! The time-slice number of the variable read from file.
! \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
!------------------------------------------------------------------------------
integer :: localrc ! local return code
type(ESMF_Logical) :: opt_singlefileflag ! helper variable
type(ESMF_IOFmt_Flag) :: opt_iofmt ! helper variable
integer :: file_ext_p
#ifdef ESMF_PIO
! initialize return code; assume routine not implemented
localrc = ESMF_RC_NOT_IMPL
if (present(rc)) rc = ESMF_RC_NOT_IMPL
! Check init status of arguments
ESMF_INIT_CHECK_DEEP_SHORT(ESMF_ArrayBundleGetInit, arraybundle, rc)
! Set default flags
opt_singlefileflag = ESMF_TRUE
if (present(singleFile)) then
if (.not. singleFile) then
opt_singlefileflag = ESMF_FALSE
end if
endif
! Set iofmt based on file name extension (if present)
if (present (iofmt)) then
opt_iofmt = iofmt
else
opt_iofmt = ESMF_IOFMT_NETCDF
end if
! Call into the C++ interface, which will call IO object
call c_esmc_arraybundleread(arraybundle, fileName, &
opt_singlefileflag, timeslice, opt_iofmt, localrc)
if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
ESMF_CONTEXT, rcToReturn=rc)) return
! Return successfully
if (present(rc)) rc = ESMF_SUCCESS
#else
! Return indicating PIO not present
call ESMF_LogSetError(rcToCheck=ESMF_RC_LIB_NOT_PRESENT, &
msg="ESMF must be compiled with PIO support to support I/O methods", &
ESMF_CONTEXT, rcToReturn=rc)
#endif
end subroutine ESMF_ArrayBundleRead