ESMF_ClockCreateNew Function

      function ESMF_ClockCreateNew(timeStep, startTime, keywordEnforcer, &
        stopTime, runDuration, runTimeStepCount, refTime, repeatDuration, name, rc)

! !RETURN VALUE:
      type(ESMF_Clock) :: ESMF_ClockCreateNew

! !ARGUMENTS:
      type(ESMF_TimeInterval), intent(in)            :: timeStep
      type(ESMF_Time),         intent(in)            :: startTime
      type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
      type(ESMF_Time),         intent(in),  optional :: stopTime
      type(ESMF_TimeInterval), intent(in),  optional :: runDuration
      integer,                 intent(in),  optional :: runTimeStepCount
      type(ESMF_Time),         intent(in),  optional :: refTime
      type(ESMF_TimeInterval), intent(in),  optional :: repeatDuration
      character (len=*),       intent(in),  optional :: name
      integer,                 intent(out), optional :: rc

!
! !STATUS:
! \begin{itemize}
! \item\apiStatusCompatibleVersion{5.2.0r}
! \item\apiStatusModifiedSinceVersion{5.2.0r}
! \begin{description}
! \item[8.7.0] Added argument {\tt repeatDuration}.
!              The new argument allows the user to specify that they want the
!              clock to be a repeat clock and repeatedly go through the same
!              interval of time.
! \end{description}
! \end{itemize}
!
! !DESCRIPTION:
!     Creates and sets the initial values in a new {\tt ESMF\_Clock}.
!
!     The arguments are:
!     \begin{description}
!     \item[timeStep]
!          The {\tt ESMF\_Clock}'s time step interval, which can be
!          positive or negative.
!     \item[startTime]
!          The {\tt ESMF\_Clock}'s starting time.  Can be less than or
!          or greater than stopTime, depending on a positive or negative
!          timeStep, respectively, and whether a stopTime is specified;
!          see below.
!     \item[{[stopTime]}]
!          The {\tt ESMF\_Clock}'s stopping time.  Can be greater than or
!          less than the startTime, depending on a positive or negative
!          timeStep, respectively.  If neither stopTime, runDuration, nor
!          runTimeStepCount is specified, clock runs "forever"; user must
!          use other means to know when to stop (e.g. ESMF\_Alarm or
!          ESMF\_ClockGet(clock, currTime)).  Mutually exclusive with
!          runDuration and runTimeStepCount.
!     \item[{[runDuration]}]
!          Alternative way to specify {\tt ESMF\_Clock}'s stopping time;
!             stopTime = startTime + runDuration.
!          Can be positive or negative, consistent with the timeStep's sign.
!          Mutually exclusive with stopTime and runTimeStepCount.
!     \item[{[runTimeStepCount]}]
!          Alternative way to specify {\tt ESMF\_Clock}'s stopping time;
!             stopTime = startTime + (runTimeStepCount * timeStep).
!          stopTime can be before startTime if timeStep is negative.
!          Mutually exclusive with stopTime and runDuration.
!     \item[{[refTime]}]
!          The {\tt ESMF\_Clock}'s reference time.  Provides reference point
!          for simulation time (see currSimTime in ESMF\_ClockGet() below).
!     \item[{[repeatDuration]}]
!          If specified and not 0, then makes {\tt ESMF\_Clock} a repeating clock that stays within
!          the range of {\tt startTime} to {\tt startTime}+{\tt repeatDuration}. For example, when advancing
!          if the current time goes past {\tt startTime}+{\tt repeatDuration}, then it resets
!          back to {\tt startTime} to continue. Currently, the repeat functionality is not supported with clocks
!          that run backwards (e.g. that have a negative timeStep). 
!     \item[{[name]}]
!          The name for the newly created clock.  If not specified, a
!          default unique name will be generated: "ClockNNN" where NNN
!          is a unique sequence number from 001 to 999.
!     \item[{[rc]}]
!          Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
!     \end{description}
!
!EOP
! !REQUIREMENTS:
!     TMG3.1, TMG3.4.4

      ! 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

      ! check inputs
      ESMF_INIT_CHECK_SHALLOW(ESMF_TimeIntervalGetInit,timeStep,rc)
      ESMF_INIT_CHECK_SHALLOW(ESMF_TimeGetInit,startTime,rc)
      ESMF_INIT_CHECK_SHALLOW(ESMF_TimeGetInit,stopTime,rc)
      ESMF_INIT_CHECK_SHALLOW(ESMF_TimeIntervalGetInit,runDuration,rc)
      ESMF_INIT_CHECK_SHALLOW(ESMF_TimeGetInit,refTime,rc)

      nameLen = 0

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

      ! invoke C to C++ entry point to allocate and initialize new clock
      call c_ESMC_ClockCreateNew(ESMF_ClockCreateNew, nameLen, name, &
                                 timeStep, startTime, stopTime, runDuration, &
                                 runTimeStepCount, refTime, repeatDuration, localrc)
      if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
        ESMF_CONTEXT, rcToReturn=rc)) return

      ! mark output as successfully initialized
      call ESMF_ClockSetInitCreated(ESMF_ClockCreateNew)

      ! Return success
      if (present(rc)) rc = ESMF_SUCCESS
      end function ESMF_ClockCreateNew