ESMF_ClockSet Subroutine

      subroutine ESMF_ClockSet(clock, keywordEnforcer, &
        timeStep, startTime, stopTime, &
        runDuration, runTimeStepCount, refTime, currTime, advanceCount, &
        direction, name, rc)

! !ARGUMENTS:
      type(ESMF_Clock),        intent(inout)         :: clock
      type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
      type(ESMF_TimeInterval), intent(in),  optional :: timeStep
      type(ESMF_Time),         intent(in),  optional :: startTime
      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_Time),         intent(in),  optional :: currTime
      integer(ESMF_KIND_I8),   intent(in),  optional :: advanceCount
      type(ESMF_Direction_Flag),    intent(in),  optional :: direction
      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\_Clock} that
!     was previously initialized via {\tt ESMF\_ClockCreate()}.
!     \end{sloppypar}
!
!     The arguments are:
!     \begin{description}
!     \item[clock]
!          The object instance to set.
!     \item[{[timeStep]}]
!          The {\tt ESMF\_Clock}'s time step interval, which can be positive or
!          negative.  This is used to change a clock's timestep property for
!          those applications that need variable timesteps.  See
!          {\tt ESMF\_ClockAdvance()} below for specifying variable timesteps
!          that are NOT saved as the clock's internal time step property.
!          See "direction" argument below for behavior with
!          {\\t ESMF\_DIRECTION\_REVERSE} direction.
!     \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.
!          See description in {\tt ESMF\_ClockCreate()} above.
!     \item[{[currTime]}]
!          The current time.
!     \item[{[advanceCount]}]
!          The number of times the clock has been timestepped.
!     \item[{[direction]}]
!          Sets the clock's time-stepping direction.  If called with
!          {\tt ESMF\_DIRECTION\_REVERSE}, sets the clock in "reverse" mode,
!          causing it to timestep back towards its startTime.  If called
!          with {\tt ESMF\_DIRECTION\_FORWARD}, sets the clock in normal,
!          "forward" mode, causing it to timestep in the direction of its
!          startTime to stopTime.  This holds true for negative timestep
!          clocks as well, which are initialized (created) with
!          stopTime < startTime.  The default mode is
!          {\tt ESMF\_DIRECTION\_FORWARD}, established at
!          {\tt ESMF\_ClockCreate()}.  timeStep can also be specified as an
!          argument at the same time, which allows for a change in magnitude
!          and/or sign of the clock's timeStep.  If not specified with
!          {\tt ESMF\_DIRECTION\_REVERSE}, the clock's current timeStep is
!          effectively negated.  If timeStep is specified, its sign is used as
!          specified; it is not negated internally.  E.g., if the specified
!          timeStep is negative and the clock is placed in
!          {\tt ESMF\_DIRECTION\_REVERSE}, subsequent calls to
!          {\tt ESMF\_ClockAdvance()} will cause the clock's current time to
!          be decremented by the new timeStep's magnitude.
!     \item[{[name]}]
!          The new name for this clock.
!     \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

      nameLen = 0

      ! check inputs
      ESMF_INIT_CHECK_DEEP(ESMF_ClockGetInit,clock,rc)
      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)
      ESMF_INIT_CHECK_SHALLOW(ESMF_TimeGetInit,currTime,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_ClockSet(clock, nameLen, name, timeStep, startTime, &
                           stopTime, runDuration, runTimeStepCount, &
                           refTime, currTime, advanceCount, direction, localrc)
      if (ESMF_LogFoundError(localrc, ESMF_ERR_PASSTHRU, &
        ESMF_CONTEXT, rcToReturn=rc)) return

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