ESMF_LogFoundError Function

  recursive function ESMF_LogFoundError(rcToCheck,  keywordEnforcer,  &
                                  msg, line, file, method, &
                                  rcToReturn, log) result (LogFoundError)
!
! !RETURN VALUE:
      logical :: LogFoundError
!
! !ARGUMENTS:
!
      integer,          intent(in),    optional :: rcToCheck
type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
      character(len=*), intent(in),    optional :: msg
      integer,          intent(in),    optional :: line
      character(len=*), intent(in),    optional :: file
      character(len=*), intent(in),    optional :: method
      integer,          intent(inout), optional :: rcToReturn
      type(ESMF_Log),   intent(inout), optional :: log

!
! !STATUS:
! \begin{itemize}
! \item\apiStatusCompatibleVersion{5.2.0r}
! \end{itemize}
!
! !DESCRIPTION:
!      This function returns {\tt .true.} when {\tt rcToCheck} indicates
!      an return code other than {\tt ESMF\_SUCCESS}, otherwise it returns
!      {\tt .false.}.
!      If an error is indicated, a ESMF predefined error message
!      will be written to the {\tt ESMF\_Log} along with a user added {\tt msg},
!      {\tt line}, {\tt file} and {\tt method}.
!
!      The arguments are:
!      \begin{description}
!
!      \item [{[rcToCheck]}]
!            Return code to check. Default is {\tt ESMF\_SUCCESS}.
!      \item [{[msg]}]
!            User-provided message string.
!      \item [{[line]}]
!            Integer source line number.  Expected to be set by
!            using the preprocessor {\tt \_\_LINE\_\_} macro.
!      \item [{[file]}]
!            User-provided source file name.
!      \item [{[method]}]
!            User-provided method string.
!      \item [{[rcToReturn]}]
!            If specified, when {\tt rcToCheck} indicates an error,
!            set the {\tt rcToReturn} to the value of {\tt rcToCheck}.
!            Otherwise, {\tt rcToReturn} is not modified.
!            This is not the return code for this function; it allows
!            the calling code to do an assignment of the error code
!            at the same time it is testing the value.
!      \item [{[log]}]
!            An optional {\tt ESMF\_Log} object that can be used instead
!            of the default Log.
!
!      \end{description}
!
!EOP

    integer:: rcToCheckInternal
    integer:: i
    logical:: masked
    type(ESMF_LogPrivate), pointer          :: alog
    character(len=ESMF_MAXSTR) :: errmsg
    integer :: msglen

    ! set default return
    LogFoundError = .FALSE.

    if (.not.present(rcToCheck)) then
      rcToCheckInternal = ESMF_SUCCESS
    else
      rcToCheckInternal = rcToCheck
    endif

    ESMF_INIT_CHECK_SET_SHALLOW(ESMF_LogGetInit,ESMF_LogInit,log)

    nullify(alog) ! ensure that the association status is well defined

    if (present(log)) then
      if (log%logTableIndex > 0) then
         alog => ESMF_LogTable(log%logTableIndex)
      endif
    else
      if (ESMF_LogDefault%logTableIndex > 0) then
        alog => ESMF_LogTable(ESMF_LogDefault%logTableIndex)
      end if
    endif

    if (associated(alog)) then

      ESMF_INIT_CHECK_SET_SHALLOW(ESMF_LogPrivateGetInit,ESMF_LogPrivateInit,alog)

      if (alog%traceFlag) then
        call ESMF_LogWrite ('called: ' // ESMF_METHOD, ESMF_LOGMSG_TRACE,  &
          line=line, file=file, method=method, log=log)
      end if

      ! check the error code
      if (rcToCheckInternal /= ESMF_SUCCESS) then
        masked = .false.
        do i=1, alog%errorMaskCount
          if (alog%errorMask(i) == rcToCheckInternal) masked = .true.
        enddo
        if (.not.masked) then
          call ESMF_Breakpoint()  ! no-op to assist debugging
          call ESMF_LogRc2Msg (rcToCheckInternal, errmsg, msglen)
          if (present(msg)) then
            errmsg = errmsg(:msglen) // " - " // msg
            msglen = len_trim (errmsg)
          end if
          call ESMF_LogWrite(errmsg(:msglen), ESMF_LOGMSG_ERROR,  &
              line=line, file=file, method=method, log=log)
          LogFoundError=.TRUE.
          if (present(rcToReturn)) rcToReturn = rcToCheckInternal
        endif
      endif
    else
      if (rcToCheckInternal /= ESMF_SUCCESS) then
        LogFoundError=.TRUE.
        if (present(rcToReturn)) rcToReturn = rcToCheckInternal
      end if
    endif

end function ESMF_LogFoundError