ESMF_TimeGet Subroutine

      subroutine ESMF_TimeGet(time, keywordEnforcer, &
        yy, yy_i8, &
        mm, dd, &
        d, d_i8, &
        h, m, &
        s, s_i8, &
        ms, us, ns, &
        d_r8, h_r8, m_r8, s_r8, &
        ms_r8, us_r8, ns_r8, &
        sN, sN_i8, sD, sD_i8, &
        calendar, calkindflag, timeZone, &
        timeString, timeStringISOFrac, &
        dayOfWeek, midMonth, &
        dayOfYear,  dayOfYear_r8, &
        dayOfYear_intvl, rc)

! !ARGUMENTS:
      type(ESMF_Time),         intent(in)            :: time
      type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
      integer(ESMF_KIND_I4),   intent(out), optional :: yy
      integer(ESMF_KIND_I8),   intent(out), optional :: yy_i8
      integer,                 intent(out), optional :: mm
      integer,                 intent(out), optional :: dd
      integer(ESMF_KIND_I4),   intent(out), optional :: d
      integer(ESMF_KIND_I8),   intent(out), optional :: d_i8
      integer(ESMF_KIND_I4),   intent(out), optional :: h
      integer(ESMF_KIND_I4),   intent(out), optional :: m
      integer(ESMF_KIND_I4),   intent(out), optional :: s
      integer(ESMF_KIND_I8),   intent(out), optional :: s_i8
      integer(ESMF_KIND_I4),   intent(out), optional :: ms
      integer(ESMF_KIND_I4),   intent(out), optional :: us
      integer(ESMF_KIND_I4),   intent(out), optional :: ns
      real(ESMF_KIND_R8),      intent(out), optional :: d_r8
      real(ESMF_KIND_R8),      intent(out), optional :: h_r8
      real(ESMF_KIND_R8),      intent(out), optional :: m_r8
      real(ESMF_KIND_R8),      intent(out), optional :: s_r8
      real(ESMF_KIND_R8),      intent(out), optional :: ms_r8
      real(ESMF_KIND_R8),      intent(out), optional :: us_r8
      real(ESMF_KIND_R8),      intent(out), optional :: ns_r8
      integer(ESMF_KIND_I4),   intent(out), optional :: sN
      integer(ESMF_KIND_I8),   intent(out), optional :: sN_i8
      integer(ESMF_KIND_I4),   intent(out), optional :: sD
      integer(ESMF_KIND_I8),   intent(out), optional :: sD_i8
      type(ESMF_Calendar),     intent(out), optional :: calendar
      type(ESMF_CalKind_Flag), intent(out), optional :: calkindflag
      integer,                 intent(out), optional :: timeZone ! not imp
      character (len=*),       intent(out), optional :: timeString
      character (len=*),       intent(out), optional :: timeStringISOFrac
      integer,                 intent(out), optional :: dayOfWeek
      type(ESMF_Time),         intent(out), optional :: midMonth
      integer(ESMF_KIND_I4),   intent(out), optional :: dayOfYear
      real(ESMF_KIND_R8),      intent(out), optional :: dayOfYear_r8
      type(ESMF_TimeInterval), intent(out), optional :: dayOfYear_intvl
      integer,                 intent(out), optional :: rc

!
! !STATUS:
! \begin{itemize}
! \item\apiStatusCompatibleVersion{5.2.0r}
! \end{itemize}
!
! !DESCRIPTION:
!     Gets the value of {\tt time} in units specified by the user
!     via Fortran optional arguments.  See {\tt ESMF\_TimeSet()} above for a
!     description of time units and calendars.
!
!     The ESMF Time Manager represents and manipulates time internally with 
!     integers to maintain precision.  Hence, user-specified floating point 
!     values are converted internally from integers.  For example, if a time
!     value is 5 and 3/8 seconds (s=5, sN=3, sD=8), and you want to get it as
!     floating point seconds, you would get 5.375 (s\_r8=5.375).
!
!     Units are bound (normalized) by the next larger unit specified.  For
!     example, if a time is defined to be 2:00 am on February 2, 2004, then
!     {\tt ESMF\_TimeGet(dd=day, h=hours, s=seconds)} would return
!       {\tt day = 2}, {\tt hours = 2}, {\tt seconds = 0},
!     whereas {\tt ESMF\_TimeGet(dd = day, s=seconds)} would return
!       {\tt day = 2}, {\tt seconds = 7200}.
!     Note that {\tt hours} and {\tt seconds} are bound by a day.  If bound
!     by a month,
!     {\tt ESMF\_TimeGet(mm=month, h=hours, s=seconds)} would return
!       {\tt month = 2}, {\tt hours = 26}, {\tt seconds = 0},
!     and {\tt ESMF\_TimeGet(mm = month, s=seconds)} would return
!       {\tt month = 2}, {\tt seconds = 93600} (26 * 3600).
!     Similarly, if bound to a year,
!     {\tt ESMF\_TimeGet(yy=year, h=hours, s=seconds)} would return
!       {\tt year = 2004}, {\tt hours = 770} (32*24 + 2), {\tt seconds = 0},
!     and {\tt ESMF\_TimeGet(yy = year, s=seconds)} would return
!       {\tt year = 2004}, {\tt seconds = 2772000} (770 * 3600).
!
!     For {\tt timeString}, {\tt timeStringISOFrac}, {\tt dayOfWeek},
!     {\tt midMonth}, {\tt dayOfYear}, {\tt dayOfYear\_intvl}, and
!     {\tt dayOfYear\_r8} described below, valid calendars are Gregorian,
!     Julian, No Leap, 360 Day and Custom calendars.  Not valid for
!     Julian Day, Modified Julian Day, or No Calendar. \\
!
!     For {\tt timeString} and {\tt timeStringISOFrac}, YYYY format returns
!     at least 4 digits; years <= 999 are padded on the left with zeroes and
!     years >= 10000 return the number of digits required.
!
!     For timeString, convert {\tt ESMF\_Time}'s value into partial ISO 8601
!     format YYYY-MM-DDThh:mm:ss[:n/d].  See ~\cite{ISO} and ~\cite{ISOnotes}.
!     See also method {\tt ESMF\_TimePrint()}.
!     
!     For timeStringISOFrac, convert {\tt ESMF\_Time}'s value into full ISO 8601
!     format YYYY-MM-DDThh:mm:ss[.f].  See ~\cite{ISO} and ~\cite{ISOnotes}.
!     See also method {\tt ESMF\_TimePrint()}.
!     
!     For dayOfWeek, gets the day of the week the given {\tt ESMF\_Time}
!     instant falls on.  ISO 8601 standard:  Monday = 1 through Sunday = 7.
!     See ~\cite{ISO} and ~\cite{ISOnotes}.
!
!     For midMonth, gets the middle time instant of the month that the given
!     {\tt ESMF\_Time} instant falls on.
!
!     For dayOfYear, gets the day of the year that the given {\tt ESMF\_Time}
!     instant falls on.  See range discussion in argument list below.
!     Return as an integer value.
!
!     For dayOfYear\_r8, gets the day of the year the given {\tt ESMF\_Time}
!     instant falls on.  See range discussion in argument list below.
!     Return as floating point value; fractional part represents the time of
!     day.
!
!     \begin{sloppypar}
!     For dayOfYear\_intvl, gets the day of the year the given {\tt ESMF\_Time}
!     instant falls on.  Return as an {\tt ESMF\_TimeInterval}.
!     \end{sloppypar}
!
!     The arguments are:
!     \begin{description}
!     \item[time]
!          The object instance to query.
!     \item[{[yy]}]
!          Integer year (32-bit).
!     \item[{[yy\_i8]}]
!          Integer year (large, 64-bit).
!     \item[{[mm]}]
!          Integer month.
!     \item[{[dd]}]
!          Integer day of the month.
!     \item[{[d]}]
!          Integer Julian date, or Modified Julian date (32-bit).
!     \item[{[d\_i8]}]
!          Integer Julian date, or Modified Julian date (large, 64-bit).
!     \item[{[h]}]
!          Integer hour.
!     \item[{[m]}]
!          Integer minute.
!     \item[{[s]}]
!          Integer second (32-bit).
!     \item[{[s\_i8]}]
!          Integer second (large, 64-bit).
!     \item[{[ms]}]
!          Integer millisecond.
!     \item[{[us]}]
!          Integer microsecond.
!     \item[{[ns]}]
!          Integer nanosecond.
!     \item[{[d\_r8]}]
!          Double precision day.
!     \item[{[h\_r8]}]
!          Double precision hour.
!     \item[{[m\_r8]}]
!          Double precision minute.
!     \item[{[s\_r8]}]
!          Double precision second.
!     \item[{[ms\_r8]}]
!          Double precision millisecond.
!     \item[{[us\_r8]}]
!          Double precision microsecond.
!     \item[{[ns\_r8]}]
!          Double precision nanosecond.
!     \item[{[sN]}]
!          Integer numerator of fractional second (sN/sD).
!     \item[{[sN\_i8]}]
!          Integer numerator of fractional second (sN\_i8/sD\_i8)
!                                                           (large, <= 64-bit).
!     \item[{[sD]}]
!          Integer denominator of fractional second (sN/sD).
!     \item[{[sD\_i8]}]
!          Integer denominator of fractional second (sN\_i8/sD\_i8)
!                                                           (large, <= 64-bit).
!     \item[{[calendar]}]
!          Associated {\tt Calendar}.
!     \item[{[calkindflag]}]
!          Associated {\tt CalKind\_Flag}.
!     \item[{[timeZone]}]
!          Associated timezone (hours offset from UCT, e.g. EST = -5).
!          (Not implemented yet).
!     \item[{[timeString]}]
!          \begin{sloppypar}
!          Convert time value to format string YYYY-MM-DDThh:mm:ss[:n/d],
!          where n/d is numerator/denominator of any fractional seconds and
!          all other units are in ISO 8601 format.  See ~\cite{ISO} and
!          ~\cite{ISOnotes}.  See also method {\tt ESMF\_TimePrint()}.
!          \end{sloppypar}
!     \item[{[timeStringISOFrac]}]
!          Convert time value to strict ISO 8601 format string
!          YYYY-MM-DDThh:mm:ss[.f], where f is decimal form of any fractional
!          seconds.  See ~\cite{ISO} and ~\cite{ISOnotes}.  See also method
!          {\tt ESMF\_TimePrint()}.
!     \item[{[dayOfWeek]}]
!          The time instant's day of the week [1-7].
!     \item[{[MidMonth]}]
!          The given time instant's middle-of-the-month time instant.
!     \item[{[dayOfYear]}]
!          The {\tt ESMF\_Time} instant's integer day of the year.
!          [1-366] for Gregorian and Julian calendars, [1-365] for No-Leap
!          calendar.  [1-360] for 360-Day calendar.  User-defined range
!          for Custom calendar.
!     \item[{[dayOfYear\_r8]}]
!          The {\tt ESMF\_Time} instant's floating point day of the year.
!          [1.x-366.x] for Gregorian and Julian calendars, [1.x-365.x] for
!          No-Leap calendar.  [1.x-360.x] for 360-Day calendar.  User-defined
!          range for Custom calendar.
!     \item[{[dayOfYear\_intvl]}]
!          The {\tt ESMF\_Time} instant's day of the year as an
!          {\tt ESMF\_TimeInterval}.
!     \item[{[rc]}]
!          Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
!     \end{description}
!
!EOP
! !REQUIREMENTS:
!     TMG2.1, TMG2.5.1, TMG2.5.6

      ! temp time string for C++ to fill
      character (len=ESMF_MAXSTR) :: tempTimeString, tempTimeStringISOFrac

      ! initialize time string lengths to zero for non-existent time string
      integer :: timeStringLen, timeStringLenISOFrac
      integer :: tempTimeStringLen, tempTimeStringLenISOFrac
      integer :: localrc                        ! local return code

      ! Assume failure until success
      if (present(rc)) rc = ESMF_RC_NOT_IMPL
      localrc = ESMF_RC_NOT_IMPL

      ! check inputs
      ESMF_INIT_CHECK_SHALLOW(ESMF_TimeGetInit,time,rc)

      timeStringLen = 0     
      timeStringLenISOFrac = 0     
      tempTimeStringLen = 0
      tempTimeStringLenISOFrac = 0

      ! if used, get length of given timeString for C++ validation
      if (present(timeString)) then
        timeStringLen = len(timeString)
      end if
      if (present(timeStringISOFrac)) then
        timeStringLenISOFrac = len(timeStringISOFrac)
      end if

      ! use optional args for any subset
      call c_ESMC_TimeGet(time, yy, yy_i8, mm, dd, d, d_i8, &
                          h, m, s, s_i8, ms, us, ns, &
                          d_r8, h_r8, m_r8, s_r8, ms_r8, us_r8, ns_r8, &
                          sN, sN_i8, sD, sD_i8, &
                          calendar, calkindflag, timeZone, &
                          timeStringLen, tempTimeStringLen, tempTimeString, &
                          timeStringLenISOFrac, tempTimeStringLenISOFrac, &
                          tempTimeStringISOFrac, &
                          dayOfWeek, MidMonth, dayOfYear, dayOfYear_r8, &
                          dayOfYear_intvl, localrc)
      if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
        ESMF_CONTEXT, rcToReturn=rc)) return

      ! copy temp time string back to given time string to restore
      !   native Fortran storage style
      if (present(timeString)) then
        timeString = tempTimeString(1:tempTimeStringLen)
      endif
      if (present(timeStringISOFrac)) then
        timeStringISOFrac = tempTimeStringISOFrac(1:tempTimeStringLenISOFrac)
      endif

      ! mark outputs as successfully initialized
      call ESMF_TimeInit(midMonth)
      call ESMF_TimeIntervalInit(dayOfYear_intvl)
      call ESMF_CalendarSetInitCreated(calendar)

      ! Return success
      if (present(rc)) rc = ESMF_SUCCESS
      end subroutine ESMF_TimeGet