subroutine ESMF_ArrayBundleWrite(arraybundle, fileName, keywordEnforcer, &
convention, purpose, singleFile, overwrite, status, timeslice, iofmt, rc)
!
! !ARGUMENTS:
type(ESMF_ArrayBundle), intent(in) :: arraybundle
character(*), intent(in) :: fileName
type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
character(*), intent(in), optional :: convention
character(*), intent(in), optional :: purpose
logical, intent(in), optional :: singleFile
logical, intent(in), optional :: overwrite
type(ESMF_FileStatus_Flag), intent(in), optional :: status
integer, intent(in), optional :: timeslice
type(ESMF_IOFmt_Flag), intent(in), optional :: iofmt
integer, intent(out), optional :: rc
!
! !DESCRIPTION:
! Write the Arrays into a file. 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}.
!
! When {\tt convention} and {\tt purpose} arguments are specified, NetCDF dimension
! labels and variable attributes are written from each Array in the ArrayBundle
! from the corresponding Attribute package. Additionally, Attributes may be
! set on the ArrayBundle level under the same Attribute package. This allows
! the specification of global attributes within the file.
! As with individual Arrays, the value associated with each name may be either
! a scalar character string, or a scalar or array of type integer, real, or
! double precision.
!
! 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 output file to which array bundle data is written.
! 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 written to a separate file. (For
! example, for a fileName of "myfile*.nc", tile 1 will be written to
! "myfile1.nc", tile 2 to "myfile2.nc", etc.)
! (This handling of the fileName for multi-tile I/O is subject to change.)
! \item[{[convention]}]
! Specifies an Attribute package associated with the ArrayBundle, and the
! contained Arrays, used to create NetCDF dimension labels and attributes
! in the file. When this argument is present, the {\tt purpose}
! argument must also be present. Use this argument only with a NetCDF
! I/O format. If binary format is used, ESMF will return an error code.
! \item[{[purpose]}]
! Specifies an Attribute package associated with the ArrayBundle, and the
! contained Arrays, used to create NetCDF dimension labels and attributes
! in the file. When this argument is present, the {\tt convention}
! argument must also be present. Use this argument only with a NetCDF
! I/O format. If binary format is used, ESMF will return an error code.
! \item[{[singleFile]}]
! A logical flag, the default is .true., i.e., all arrays in the bundle
! are written in one single file. If .false., each array will be written
! 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[{[overwrite]}]
! \begin{sloppypar}
! A logical flag, the default is .false., i.e., existing Array data may
! {\em not} be overwritten. If .true., only the
! data corresponding to each Array's name will be
! be overwritten. If the {\tt timeslice} option is given, only data for
! the given timeslice may be overwritten.
! Note that it is always an error to attempt to overwrite a NetCDF
! variable with data which has a different shape.
! \end{sloppypar}
! \item[{[status]}]
! \begin{sloppypar}
! The file status. Please see Section~\ref{const:filestatusflag} for
! the list of options. If not present, defaults to
! {\tt ESMF\_FILESTATUS\_UNKNOWN}.
! \end{sloppypar}
! \item[{[timeslice]}]
! \begin{sloppypar}
! Some I/O formats (e.g. NetCDF) support the output of data in form of
! time slices. The {\tt timeslice} argument provides access to this
! capability. {\tt timeslice} must be positive. The behavior of this
! option may depend on the setting of the {\tt overwrite} flag:
! \begin{description}
! \item[{\tt overwrite = .false.}:]\ If the timeslice value is
! less than the maximum time already in the file, the write will fail.
! \item[{\tt overwrite = .true.}:]\ Any positive timeslice value is valid.
! \end{description}
! By default, i.e. by omitting the {\tt timeslice} argument, no
! provisions for time slicing are made in the output file,
! however, if the file already contains a time axis for the variable,
! a timeslice one greater than the maximum will be written.
! \end{sloppypar}
! \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
integer :: len_varName ! helper variable
type(ESMF_Logical) :: opt_overwriteflag ! helper variable
type(ESMF_FileStatus_Flag) :: opt_status ! 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)
! Attributes
if (present (convention) .neqv. present (purpose)) then
if (ESMF_LogFoundError (ESMF_RC_ARG_WRONG, &
msg='Both convention and purpose must be specified', &
ESMF_CONTEXT, rcToReturn=rc)) return
end if
! Set default flags
opt_singlefileflag = ESMF_TRUE
if (present(singleFile)) opt_singlefileflag = singlefile
opt_overwriteflag = ESMF_FALSE
if (present(overwrite)) opt_overwriteflag = overwrite
opt_status = ESMF_FILESTATUS_UNKNOWN
if (present(status)) opt_status = status
! 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_arraybundlewrite(arraybundle, fileName, &
convention, purpose, &
opt_singlefileflag, opt_overwriteflag, opt_status, &
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_ArrayBundleWrite