ESMF_AlarmSet Subroutine

      subroutine ESMF_AlarmSet(alarm, keywordEnforcer, &
        clock, ringTime, ringInterval, stopTime, ringDuration, &
        ringTimeStepCount, refTime, ringing, enabled, sticky, name, rc)

! !ARGUMENTS:
      type(ESMF_Alarm),        intent(inout)         :: alarm
      type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
      type(ESMF_Clock),        intent(in),  optional :: clock
      type(ESMF_Time),         intent(in),  optional :: ringTime
      type(ESMF_TimeInterval), intent(in),  optional :: ringInterval
      type(ESMF_Time),         intent(in),  optional :: stopTime
      type(ESMF_TimeInterval), intent(in),  optional :: ringDuration
      integer,                 intent(in),  optional :: ringTimeStepCount
      type(ESMF_Time),         intent(in),  optional :: refTime
      logical,                 intent(in),  optional :: ringing
      logical,                 intent(in),  optional :: enabled
      logical,                 intent(in),  optional :: sticky
      character (len=*),       intent(in),  optional :: name
      integer,                 intent(out), optional :: rc

!
! !STATUS:
! \begin{itemize}
! \item\apiStatusCompatibleVersion{5.2.0r}
! \end{itemize}
!
! !DESCRIPTION:
!     \begin{sloppypar}
!     Sets/resets one or more of the properties of an {\tt ESMF\_Alarm} that
!     was previously initialized via {\tt ESMF\_AlarmCreate()}.
!     \end{sloppypar}
!
!     The arguments are:
!     \begin{description}
!     \item[alarm]
!          The object instance to set.
!     \item[{[clock]}]
!          Re-associates this alarm with a different clock.
!     \item[{[ringTime]}]
!          The next ring time for a one-shot alarm or a repeating (interval)
!          alarm.
!     \item[{[ringInterval]}]
!          The ring interval for repeating (interval) alarms.
!     \item[{[stopTime]}]
!          The stop time for repeating (interval) alarms.
!     \item[{[ringDuration]}]
!          The absolute ring duration.  If not sticky (see argument below),
!          alarms rings for ringDuration, then turns itself off.  Default is
!          zero (unused).  Mutually exclusive with ringTimeStepCount (below);
!          used only if set to a non-zero duration and ringTimeStepCount is 1
!          (see below).
!          See also {\tt ESMF\_AlarmSticky()}, {\tt ESMF\_AlarmNotSticky()}.
!     \item[{[ringTimeStepCount]}]
!          The relative ring duration.  If not sticky (see argument below),
!          alarms rings for ringTimeStepCount, then turns itself off.
!          Default is 1: a non-sticky alarm will ring for one clock time step.
!          Mutually exclusive with ringDuration (above); used if
!          ringTimeStepCount > 1.  If ringTimeStepCount is 1 (default) and
!          ringDuration is non-zero, ringDuration is used (see above), otherwise
!          ringTimeStepCount is used.
!          See also {\tt ESMF\_AlarmSticky()}, {\tt ESMF\_AlarmNotSticky()}.
!     \item[{[refTime]}]
!          The reference (i.e. base) time for an interval alarm.
!     \item[{[ringing]}]
!          Sets the ringing state.
!          See also {\tt ESMF\_AlarmRingerOn()}, {\tt ESMF\_AlarmRingerOff()}.
!     \item[{[enabled]}]
!          Sets the enabled state.  If disabled, an alarm will not function
!          at all.
!          See also {\tt ESMF\_AlarmEnable()}, {\tt ESMF\_AlarmDisable()}.
!     \item[{[sticky]}]
!          Sets the sticky state.  If sticky, once an alarm is ringing, it
!          will remain ringing until turned off manually via a user call to
!          {\tt ESMF\_AlarmRingerOff()}.  If not sticky, an alarm will turn
!          itself off after a certain ring duration specified by either
!          ringDuration or ringTimeStepCount (see above).
!          There is an implicit limitation that in order to properly reverse
!          timestep through a ring end time in {\tt ESMF\_DIRECTION\_REVERSE},
!          that time must have already been traversed in the forward direction.
!          This is due to the fact that the Time Manager cannot predict when
!          user code will call {\tt ESMF\_AlarmRingerOff()}.  An error message
!          will be logged when this limitation is not satisfied.
!          See also {\tt ESMF\_AlarmSticky()}, {\tt ESMF\_AlarmNotSticky()}.
!     \item[{[name]}]
!          The new name for this alarm.
!     \item[{[rc]}]
!          Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
!     \end{description}
!
!EOP
! !REQUIREMENTS:
!     TMG4.1, TMG4.7

      ! initialize name length to zero for non-existent name
      integer :: nameLen, localrc

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

      nameLen = 0

      ! check inputs
      ESMF_INIT_CHECK_DEEP(ESMF_AlarmGetInit,alarm,rc)
      ESMF_INIT_CHECK_DEEP(ESMF_ClockGetInit,clock,rc)
      ESMF_INIT_CHECK_SHALLOW(ESMF_TimeGetInit,ringTime,rc)
      ESMF_INIT_CHECK_SHALLOW(ESMF_TimeIntervalGetInit,ringInterval,rc)
      ESMF_INIT_CHECK_SHALLOW(ESMF_TimeGetInit,stopTime,rc)
      ESMF_INIT_CHECK_SHALLOW(ESMF_TimeIntervalGetInit,ringDuration,rc)
      ESMF_INIT_CHECK_SHALLOW(ESMF_TimeGetInit,refTime,rc)

      ! get length of given name for C++ validation
      if (present(name)) then
        nameLen = len_trim(name)
      end if

      ! invoke C to C++ entry point
      call c_ESMC_AlarmSet(alarm, nameLen, name, clock, ringTime, &
                           ringInterval, stopTime, ringDuration, &
                           ringTimeStepCount, refTime, ringing, &
                           enabled, sticky, localrc)
      if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
        ESMF_CONTEXT, rcToReturn=rc)) return

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